RESTful API定义及管理指南_restful api管理-优快云博客

本文链接：https://blog.youkuaiyun.com/weixin_58029845/article/details/120151161

作者 | Damon 爱数AnyShare引擎研发部-开发经理

OAS 3.0
OAS 3.0与RESTful API
使用OAS 3.0
整体流程
使用案例
编辑器
文本编辑器
GUI编辑器
JSON Schema
文档展示
SDK
Mock
概述
使用方法
上传 API 文档
Mock 地址配置
参考资料

OAS 3.0

API specifications可以使用YAML或JSON编写。该格式对人类和机器来说都是容易学习和读取的。完整的OpenAPI Specification参考GitHub：OpenAPI 3.0 Specification

OAS 3.0与RESTful API

使用OAS 3.0

整体流程

使用案例

说明：

编辑阶段：开发者进行编辑，可以选择本地或在线编辑器
编辑完成：将 swaggerJSON上传到 git，保证代码和 API 版本一致
查看阶段：从 Git上 pull API 代码，在 PC上使用 vscode查看或者在 redoc上查看，YAPI也可提供查看功能
测试阶段：从 Git上 pull API代码，同步到 YAPI环境
发布阶段：Jenkins每日构建过程中，都是用 API文件构建生成 HTML文档

编辑器

文本编辑器

vscode插件：

OpenAPI (Swagger) Editor
openapi-lint
ReDoc Viewer

由于YAPI 只支持 JSON 格式的文件导入，所以推荐使用 JSON 格式存储

插件配合使用效果

注意：ReDoc Viewer插件可能有bug，第一个窗口port为9093，替换ip后即可访问，开第二个vscode窗口后，使用了错误的port，除替换ip，还要替换port为9094，再新开窗口则port依次递增。

GUI编辑器

APICURIO

安装指南：https://github.com/Apicurio/apicurio-studio/tree/master/distro/docker-compose

JSON Schema

无论是接口的返回值还是传入参数，都会大量使用到 json 对象，在 API 编辑的过程中，JSON Schema 编写是比较困难的，解决方法：

使用文本编辑器时，可以使用在线的 JSON Schema 生成器：https://jsonschema.net，并进行必要的删减
使用 APICURIO，可以使用自带的 JSON Schema 生成功能，并做必要的修改

文档展示

统一使用redoc-cli

安装：

mkdir /nodejs && cd /nodejs
npm i redoc-cli

启动服务端：

-p：指定服务端口号
--watch：监测指定文件/文件夹的变更（若不指定表示检测所在文件夹），刷新页面可获取最新内容
--ssr：服务器端渲染（可选）

node /nodejs/node_modules/redoc-cli/index.js serve -p 7777 --watch=./xx.json --ssr --options.requiredPropsFirst --options.jsonSampleExpandLevel=all --options.disableSearch --options.pathInMiddlePanel --options.menuToggle --options.theme.colors.primary.main=#E60F19 --title='xxx' -t /root/api/template.hbs ./xx.json

生成HTML文件：

node /nodejs/node_modules/redoc-cli/index.js bundle --options.requiredPropsFirst --options.jsonSampleExpandLevel=all --options.disableSearch --options.pathInMiddlePanel --options.menuToggle --options.theme.colors.primary.main=#E60F19 --title='xxx' -t /root/api/template.hbs ./xx.json -o ./xx.html

命令中使用的模板：

/root/api/template.hbs
<!DOCTYPE html>
<html>
  
<head>
  <meta charset="utf8" />
  <title>{{title}}</title>
  <!-- needed for adaptive design -->
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body {
      padding: 0;
      margin: 0;
    }
  </style>
  {{{redocHead}}}
  <link href="https://fonts.googleapis.com/css?family=Noto+Sans+SC:300,400,700&display=swap&subset=chinese-simplified" rel="stylesheet">
</head>
  
<body>
  {{{redocHTML}}}
</body>
  
</html>

AnyShare OpenDoc API: