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管理项目
接口描述
接口版本
-
接口对应服务器地址
参考： Doclever界面风格
编辑API接口
根据接口对应服务器地址获取/openapi/3.0/api.json
如果接口对应服务器能够获取JSON文件，则解析JSON生成接口文档，同时锁定接口（不可修改）
-
当接口对应服务器地址无法获取JSON文件时，可创建编辑接口
参考： Swagger UI 解析OAS3.0 的JSON文件
生成客户端/服务端代码
-
根据api.json文件生成404框架下的客户端/服务端代码
参考： Swagger Codegen
修改接口代码
-
在自动生成的代码上进行接口开发和改造
参考： 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文档
