Fork me on GitHub

Swagger DOCS


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

Swagger 编辑器文档

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






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


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


npm install;


Swagger Editor 可以在GibHub的共有仓库上找到。


npm install -g http-server
http-server swagger-editor




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


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


git clone
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上面找到.



| 版本 | 发布时间 |规范兼容版本|说明 | ------| ------ | :----: | | 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|




  • Java, version 7 or higher

Installation with Homebrew

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

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


假设我们已经安装好了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>


swagger-codegen generate -i -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 -l csharp




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


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


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:
  • C#:
  • C++:
  • Haskell:
  • Java:
  • JavaScript:
  • Groovy:
  • Go:
  • ObjC:
  • Perl:
  • PHP:
  • Python:
  • Ruby:
  • Scala:
  • Swift:
  • TypeScript:

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 If you've addaed new vendor extensions as part of your PR, please update the wiki page.


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/ 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 to run the CI tests by adding your own Swagger-Codegen repository.


  • 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 to run the CI tests)
  • File a PR with meaningful title, description and commit messages. A good example is PR-3306