API管理平台设想

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文档

你可能感兴趣的:(API管理平台设想)