Swagger 体系

​ 首先有人定义了一个API文档产生的规范，前期叫Swagger，后面贡献给了Linux基金会，逐渐演变成OpenAPI Specification，逐渐成为世界级别的规范，即OAS，它定义了一种JSON格式或者YAML格式的API文档文件格式；而Swagger提供了Swagger Editor来帮助开发人员熟悉和编写正确的符合OpenAPI规范的API文档文件，这个文件可以使JSON格式的，也可以是YAML格式的；Swagger又提供了Swagger Codegen来生成API文档对应的代码，Swagger Codegen来展示API文档，Swagger Inspector来测试API对应的代码；最后Springfox结合Spring与Swagger，帮助开发人员自动生成对应代码的对应API。

API管理平台设想

使用步骤

创建API管理项目

1. 接口描述

2. 接口版本

3. 接口对应服务器地址

   参考： Doclever界面风格

编辑API接口

1. 根据接口对应服务器地址获取/openapi/3.0/api.json

2. 如果接口对应服务器能够获取JSON文件，则解析JSON生成接口文档，同时锁定接口（不可修改）

3. 当接口对应服务器地址无法获取JSON文件时，可创建编辑接口

   参考： Swagger UI 解析OAS3.0 的JSON文件

生成客户端/服务端代码

1. 根据api.json文件生成404框架下的客户端/服务端代码

   参考： Swagger Codegen

修改接口代码

1. 在自动生成的代码上进行接口开发和改造

   参考： Springfox + Swagger2

参考源码

OAS 3.0

​ https://github.com/OAI/OpenAPI-Specification

• openapi object ： 版本描述

• info object ：接口描述

• servers object：服务端信息

• paths object：接口列表

• components object：引用组件

• security object：安全模块

• tags object：分类标签

• extemalDocs object：外部文档

  VS 2.0 https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

Swagger Codegen

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

• 解析JSON，基于Mustache模板引擎技术，根据模板生成指定语言代码
• JMustache VS Handlerbars.java（默认）
• 支持 Swagger2.0、OAS3.0

Swagger UI

​ https://github.com/swagger-api/swagger-ui

• 支持 Swagger2.0、OAS3.0
• Chrome, Safari, Firefox, Edge , IE11
• ReactJs

Springfox-swagger2

​ https://github.com/springfox/springfox/tree/master/springfox-swagger2

• 目前不支持 OAS3.0 正在建设中...

DoClever

• 支持导入 Swagger2.0 文档
• 不支持导入 OAS3.0 文档
• 不支持导出Swagger/OAS文档

SosoApi

• 开源版不支持导出 swagger文档
• 专业版只支持 swagger2.0 文档导出

待开发

UI

• 创建API项目
• 接口可视化编辑
• 根据OAS文档生成可视化接口

代码生成

• 编写mustache模板文件
• 编写swagger-codegen自定义模板插件

自定义注解

• 编写自定义注解
• 根据注解生成OAS文档