Fork me on GitHub

Swagger DOCS

概述

Swagger文档包含了一些有用的参考和简单的帮助信息,能够快速的使用Swagger 工具编辑你的API.

Swagger 编辑器文档

Swagger Editor是一个开源的编辑器,基于Swagger规范来定义RESTful APIs文档信息,Swagger Editor源代码可以在GitHub上找到。

GitHub: https://github.com/swagger-api/swagger-editor

Download

在web浏览器上使用编辑器

这个编辑器可以在任意web浏览器上工作,可以在本机访问或者在从web服务器访问。

本机上使用编辑器

你可以在你的机器上运行和使用Swagger Editor。

先决条件

在你下载并且运行Swagger Editor之前,你需要安装下面列出的依赖环境:

一旦NodeJS安装成功,通过npm的install命令安装所有的依赖。

npm install;

使用http-server运行Editor

Swagger Editor 可以在GibHub的共有仓库上找到。 https://github.com/swagger-api/swagger-editor

通过http-server模块来运行编辑器,从Github上面下载最后一个稳定版本,在你的终端上运行以下脚本:

1
2
3
4
npm install -g http-server
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
unzip swagger-editor.zip
http-server swagger-editor

通过Docker运行编辑器

编辑器可以在Docker公共仓库找到。 https://hub.docker.com/r/swaggerapi/swagger-editor/

通过以下脚本运行编辑器:

1
2
docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor

贡献

Swagger 编辑器是一个基于Apache license的开源项目。你可以把你的建议,想法,bug共享到这个项目中,通过pull requests到Swagger Editor GitHub

按照以下流程在你的机器上运行编辑器:

1
2
3
4
5
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm run build
npm start

常见问题

  • 如果npm start 不能够工作,就删除node_modules文件夹,然后运行npm install 和npm start
  • 如果dist目录出现了问题,通过root权限去执行npm run build

Swagger 代码生成文档

Swagger代码生成工具是一个开源的工具,能够从一个Swagger定义的RESTful API来构建服务端和客户端的SDK文件。Swagger代码生成工具也可以在GitHub上面找到.

GitHub: https://github.com/swagger-api/swagger-codegen

兼容性

| 版本 | 发布时间 |规范兼容版本|说明 | ------| ------ | :----: | | 2.3.0 (upcoming minor release)|TBD|1.0, 1.1, 1.2, 2.0|Minor releases with breaking changes| | 2.2.2 (upcoming patch release)|TBD|1.0, 1.1, 1.2, 2.0|Patch release (without breaking changes)| | 2.2.1 (current stable)|2016-08-07|1.0, 1.1, 1.2, 2.0| tag v2.2.1| | 2.1.6|2016-04-06|1.0, 1.1, 1.2, 2.0|tag v2.1.6| | 2.0.17|2014-08-22|1.1, 1.2|tag v2.0.17| | 1.0.4|2012-04-12|1.0, 1.1|tag v1.0.4|

安装

先决条件

在你机子下载运行Swagger代码生成工具之前需要安装以下的依赖环境:

  • Java, version 7 or higher

Installation with Homebrew

如果你是mac或者linux环境,你可以通过Homebrew来安装Swagger Codegen。

1
brew install swagger-codegen

Installation from Maven Central

所有的Swagger Codegen版本都可以在Maven Central找到,并且你可以选择适合的版本(我们推荐最后一个版本).

你可以下载并运行这个executable .jar文件(比如:swagger-codegen-cli-2.2.1.jar)

或者你可以使用wget命令下载: wget {link address of the executable .jar file}

例如: wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar

用法

假设我们已经安装好了swagger-codegen-cli-2.2.1,你可以访问wagger Codegen 安装章节来学习怎么在你的机器上安装。

List of supported languages

To get a list of languages supported by the Swagger Codegen - Swagger Codegen可以获取多种语言的列表信息。 如果你安装了Homebrew,执行以下命令: swagger-codegen 或者你也可以使用以下命令: java -jar swagger-codegen-cli-2.2.1.jar

Help options in terminal

执行以下命令可以获取帮助信息。 如果你安装了Homebrew,执行以下命令: swagger-codegen help 或者你也可以使用以下命令: java -jar swagger-codegen-cli-2.2.1.jar help

你也可以了解具体的某个命令的用法: 如果你安装了Homebrew,执行以下命令: swagger-codegen help <command> Example: swagger-codegen help generate 或者你也可以使用以下命令: java -jar swagger-codegen-cli-2.2.1.jar help Example: java -jar swagger-codegen-cli-2.2.1.jar help generate

你也可以了解某个语言的帮助信息: If you have Homebrew installed: swagger-codegen config-help -l <language name> Example: swagger-codegen config-help -l php Else, you could use: java -jar swagger-codegen-cli-2.2.1.jar config-help -l <language name> Example: java -jar swagger-codegen-cli-2.2.1.jar config-help -l php

Once you have the various help section options, you can learn about a specific topic. If you have Homebrew installed: swagger-codegen help <command> Example: swagger-codegen help generate Else, you could use: java -jar swagger-codegen-cli-2.2.1.jar help Example: java -jar swagger-codegen-cli-2.2.1.jar help generate

代码生成

从一个已经编写好的swagger 规范中生成代码. If you have Homebrew installed:

swagger-codegen generate -i <path of your Swagger specification> -l <language>

Example:

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l csharp

Else, you could use:

java -jar swagger-codegen-cli-2.2.1.jar -i <path of your Swagger specification> -l <language> ` Example:

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l csharp

在上面的代码中,我们通过2个参数:-i和-l来执行.-i指向了你的api规范文件路径。-l代表了你想要生成某个语言的代码。

生成工具有一个README文件,包含了所有的运行和构建api的信息。通过了解它来构建你的API.

贡献

Swagger生成工具也是基于Apache协议的开源项目,如果你有什么建议,想法,bug都可以提交到GitHub repository,地址: https://github.com/swagger-api/swagger-codegen.

指南

Before submitting an issue

  • If you're not using the latest master to generate API clients or server stubs, please give it another try by pulling the latest master as the issue may have already been addressed. Ref: Getting Started
  • Search the open issue and closed issue to ensure no one else has reported something similar before.
  • File an issue ticket by providing all the required information.
  • Test with the latest master by building the JAR locally to see if the issue has already been addressed.
  • You can also make a suggestion or ask a question by opening an "issue".

Before submitting a PR

  • Search the open issue to ensure no one else has reported something similar and no one is actively working on similar proposed change.
  • If no one has suggested something similar, open an "issue" with your suggestion to gather feedback from the community.
  • It's recommended to create a new git branch for the change so that the merge commit message looks nicer in the commit history.

How to contribute

Code generators

All the code generators can be found in modules/swagger-codegen/src/main/java/io/swagger/codegen/languages

Templates

All the templates (mustache) can be found in modules/swagger-codegen/src/main/resources.

For a list of variables available in the template, please refer to this page

Style guide

Code change should conform to the programming style guide of the respective langauages:

  • Android: https://source.android.com/source/code-style.html
  • C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx
  • C++: https://google.github.io/styleguide/cppguide.html
  • Haskell: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
  • Java: https://google.github.io/styleguide/javaguide.html
  • JavaScript: https://github.com/airbnb/javascript/tree/master/es5
  • Groovy: http://groovy-lang.org/style-guide.html
  • Go: https://github.com/golang/go/wiki/CodeReviewComments
  • ObjC: https://github.com/NYTimes/objective-c-style-guide
  • Perl: http://perldoc.perl.org/perlstyle.html
  • PHP: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
  • Python: https://www.python.org/dev/peps/pep-0008/
  • Ruby: https://github.com/bbatsov/ruby-style-guide
  • Scala: http://docs.scala-lang.org/style/
  • Swift: https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/Swift_Programming_Language/TheBasics.html
  • TypeScript: https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines

For other languages, feel free to suggest.

You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those.

For Vendor Extensions, please follow the naming convention below:

  • For general vendor extension, use lower case and hyphen. e.g. x-is-unique, x-content-type
  • For language-specified vendor extension, put it in the form of x-{lang}-{extension-name}. e.g. x-objc-operation-id, x-java-feign-retry-limit
  • For a list of existing vendor extensions in use, please refer to https://github.com/swagger-api/swagger-codegen/wiki/Vendor-Extensions. If you've addaed new vendor extensions as part of your PR, please update the wiki page.

Testing

To add test cases (optional) covering the change in the code generator, please refer to modules/swagger-codegen/src/test/java/io/swagger/codegen

To test the templates, please perform the following:

  • Update the Petstore sample by running the shell script under bin folder. For example, run ./bin/ruby-petstore.sh to update the Ruby PetStore API client under samples/client/petstore/ruby For Windows, the batch files can be found under bin\windows folder. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI/Swagger spec from time to time. If you've questions or concerns, please open a ticket to start a discussion)
  • Run the tests in the sample folder, e.g. in samples/client/petstore/ruby, run mvn integration-test -rf :RubyPetstoreClientTests. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)
  • Finally, git commit the updated samples files: git commit -a (git add -A if added files with new test cases)

To start the CI tests, you can run mvn verify -Psamples (assuming you've all the required tools installed to run tests for different languages) or you can leverage http://travis-ci.org to run the CI tests by adding your own Swagger-Codegen repository.

Tips

  • Smaller changes are easier to review
  • [Optional] For bug fixes, provide a OpenAPI Spec to repeat the issue so that the reviewer can use it to confirm the fix
  • Add test case(s) to cover the change
  • Document the fix in the code to make the code more readable
  • Make sure test cases passed after the change (one way is to leverage https://travis-ci.org/ to run the CI tests)
  • File a PR with meaningful title, description and commit messages. A good example is PR-3306