Swagger总结

概念

Swagger是一款REST APIs文档生成工具。Swagger官方定义：
Swagger是一款开源工具，依据OpenAPI规范（OpenAPI Specification，简称OAS）可以帮助你设计，构建，生成文档，消费（调用）REST APIs。主要的工具包含：
Swagger Editor：基于web的一个工具，用于编写符合OpenAPI规范的模型
Swagger UI：用于展示REST APIs文档，并提供一些交互操作
Swagger Codegen： 依据OpenAPI规范来生成服务端和客户端代码

 

传统的APIs文档是通过手工编写而成，存在如下弊端

1. 文档和代码处于不同的位置，文档需要开发人员来维护，对接口的增删改查需要在文档中进行同步。

2. 文档格式不统一。

3. 文档共享需要借助外部工具或者自己开发网站。

Swagger特征

1. 通过代码和注释自动生成文档。在Swagger框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的REST APIs文档

2. 提供了UI界面。既展示接口信息，又提供了参数校验，测试功能

3. 形成了文档规范，支持不同的语言

4. 提供丰富的组件。

 

Resful APIs文档生成工具有哪些？

Spring RESTDOC
 github地址：https://github.com/spring-projects/spring-restdocs

Swagger
github 地址：https://github.com/swagger-api/swagger-core

apiDoc
Git地址：https://github.com/apidoc/apidoc  

 

OpenAPI 规范

OpenAPI定义了RESTful APIs的编写规范。规范中指定了一套模式/模型。这套规范是Swagger为各种编程语言编写的服务提供接口文档奠定了基础。

主要的模型

OpenAPI Object
文档根对象，持有其他对象的引用

Info Object
整个文档的描述，Summery

Paths Object
路径集合，包含多个路径

Path Item Object
路径项信息，描述接口的路径

Operation Object
操作，代表Resftul APIs的某一接口

Parameter Object
参数信息

Request Body Object
请求体

响应集合，包含错误，正确响应结果的集合

Response Object
响应对象

案例

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API overview",
    "version": "v2"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 300 response",
            "examples": {
              "application/json": "{\n    \"versions\": [\n        {\n            \"status\": \"CURRENT\",\n            \"updated\": \"2011-01-21T11:33:21Z\",\n            \"id\": \"v2.0\",\n            \"links\": [\n                {\n                    \"href\": \"http://127.0.0.1:8774/v2/\",\n                    \"rel\": \"self\"\n                }\n            ]\n        },\n        {\n            \"status\": \"EXPERIMENTAL\",\n            \"updated\": \"2013-07-23T11:33:21Z\",\n            \"id\": \"v3.0\",\n            \"links\": [\n                {\n                    \"href\": \"http://127.0.0.1:8774/v3/\",\n                    \"rel\": \"self\"\n                }\n            ]\n        }\n    ]\n}"
            }
          },
          "300": {
            "description": "200 300 response",
            "examples": {
              "application/json": "{\n    \"versions\": [\n        {\n            \"status\": \"CURRENT\",\n            \"updated\": \"2011-01-21T11:33:21Z\",\n            \"id\": \"v2.0\",\n            \"links\": [\n                {\n                    \"href\": \"http://127.0.0.1:8774/v2/\",\n                    \"rel\": \"self\"\n                }\n            ]\n        },\n        {\n            \"status\": \"EXPERIMENTAL\",\n            \"updated\": \"2013-07-23T11:33:21Z\",\n            \"id\": \"v3.0\",\n            \"links\": [\n                {\n                    \"href\": \"http://127.0.0.1:8774/v3/\",\n                    \"rel\": \"self\"\n                }\n            ]\n        }\n    ]\n}"
            }
          }
        }
      }
    },
    "/v2": {
      "get": {
        "operationId": "getVersionDetailsv2",
        "summary": "Show API version details",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 203 response",
            "examples": {
              "application/json": "{\n    \"version\": {\n        \"status\": \"CURRENT\",\n        \"updated\": \"2011-01-21T11:33:21Z\",\n        \"media-types\": [\n            {\n                \"base\": \"application/xml\",\n                \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n            },\n            {\n                \"base\": \"application/json\",\n                \"type\": \"application/vnd.openstack.compute+json;version=2\"\n            }\n        ],\n        \"id\": \"v2.0\",\n        \"links\": [\n            {\n                \"href\": \"http://127.0.0.1:8774/v2/\",\n                \"rel\": \"self\"\n            },\n            {\n                \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n                \"type\": \"application/pdf\",\n                \"rel\": \"describedby\"\n            },\n            {\n                \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n                \"type\": \"application/vnd.sun.wadl+xml\",\n                \"rel\": \"describedby\"\n            },\n            {\n              \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n              \"type\": \"application/vnd.sun.wadl+xml\",\n              \"rel\": \"describedby\"\n            }\n        ]\n    }\n}"
            }
          },
          "203": {
            "description": "200 203 response",
            "examples": {
              "application/json": "{\n    \"version\": {\n        \"status\": \"CURRENT\",\n        \"updated\": \"2011-01-21T11:33:21Z\",\n        \"media-types\": [\n            {\n                \"base\": \"application/xml\",\n                \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n            },\n            {\n                \"base\": \"application/json\",\n                \"type\": \"application/vnd.openstack.compute+json;version=2\"\n            }\n        ],\n        \"id\": \"v2.0\",\n        \"links\": [\n            {\n                \"href\": \"http://23.253.228.211:8774/v2/\",\n                \"rel\": \"self\"\n            },\n            {\n                \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n                \"type\": \"application/pdf\",\n                \"rel\": \"describedby\"\n            },\n            {\n                \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n                \"type\": \"application/vnd.sun.wadl+xml\",\n                \"rel\": \"describedby\"\n            }\n        ]\n    }\n}"
            }
          }
        }
      }
    }
  },
  "consumes": [
    "application/json"
  ]
}

详细参考OpenAPI Specification

 

Swagger工具

略，详见下面链接

swagger-editor

swagger-codegen

swagger-ui

Java实操

Swagger对Java的支持程度

Swagger Codegen不支持生成Java服务端，显而易见，Spring MVC已经是Java程序中一套成熟的，用来搭建Restful API的框架，依赖于Spring,Spring Boot,Swagger无需重新发明轮子。

Swagger对Java支持主要来自io.springfox提供的包

        io.springfox
        springfox-swagger2
        2.7.0


         io.springfox
         springfox-swagger-ui
         2.7.0
 

 

springfox

springfox 文档

案例

Spring Boot集成Swagger

 

参考文章

specification about

OpenAPI specification

OpenAPI-Specification Example