Api: Swagger


API 使用 HTTP 状态码还是全部返回 200 - V2EX

界面 Restful API Library/Client OpenAPI(Swagger) Export/Import UseCase Demo/Docs Cons/Pros
Mock Server 全面 支持 - 国际 swagger hub, schema 成熟稳定
YApi 友好 支持导入 可以 国内
RAP2 友好 demo, wiki
Mockoon 非常友好 可以 上手快
brew install swagger-codegen
swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l spring --additional-properties java8=true  -o /tmp/javatest
java -jar swagger-codegen-cli-2.4.0.jar generate -i http://petstore.swagger.io/v2/swagger.json -l python -o /tmp/pytest
java -jar swagger-codegen-cli-2.4.0.jar generate -i http://petstore.swagger.io/v2/swagger.json -l python-flask -o /tmp/flasktest
swagger-codegen config-help -l java
  1. swagger-api/swagger-codegen#8976
  2. bodyusername should be body, username
[ERROR] /private/tmp/javatest/src/test/java/io/swagger/api/UserApiControllerIntegrationTest.java:[77,62] cannot find symbol
[ERROR]   symbol:   variable bodyusername
[ERROR]   location: class io.swagger.api.UserApiControllerIntegrationTest

Known issues

  1. Server stub generator HOWTO
  2. API client generator HOWTO
  3. What Is the Difference Between Swagger and OpenAPI?

  4. OpenAPI = Specification

  5. Swagger = Tools for implementing the specification

These tools include:

  • Swagger Editor: Swagger Editor lets you edit OpenAPI specifications in YAML inside your browser and to preview documentations in real time.
  • Swagger UI: Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.
  • Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec.
  • Swagger Parser: Standalone library for parsing OpenAPI definitions from Java
  • Swagger Core: Java-related libraries for creating, consuming, and working with OpenAPI definitions
  • Swagger Inspector (free): API testing tool that lets you validate your APIs & generate OpenAPI definitions from an existing API
  • SwaggerHub (free and commercial): API design and documentation, built for teams working with OpenAPI.