Write By CS逍遥剑仙
我的主页: csxiaoyao.com
GitHub: github.com/csxiaoyaojianxian
Email: sunjianfeng@csxiaoyao.com
QQ: 1724338257
swagger 是一个 RESTful 接口的基于 YAML、JSON 语言的文档和代码在线自动生成工具,它让部署管理 API 变得前所未有的简单。swagger 在 java 界广为使用,其他语言同样可以方便地集成使用。本文以基于 node.js 的企业级应用框架 egg.js 为例,集成 swagger 以根据函数注释自动生成接口文档。
参考链接:https://github.com/csxiaoyaojianxian/JavaScriptStudy/tree/master/17-nodejs/20-egg-swagger-doc
egg 有两种搭建方式:快速搭建和普通搭建。由于本案例比较简单,为了避免项目多余的配置,此处使用普通的搭建方式,可以参考上面的链接,搭建的项目目录结构如下:
egg-example ├── app │ ├── contract │ │ └── format.js │ ├── controller │ │ └── home.js │ └── router.js ├── config │ └── config.default.js │ └── plugin.js └── package.json
其中,包含了一个路由 /index
调用了 HomeController
控制器的 index
方法,下面将对该路由进行 swagger 处理。
参考 npm 项目: https://www.npmjs.com/package/egg-swagger-doc 在 egg 项目中安装 swagger:
$ npm i egg-swagger-doc --save
首先在 egg 中启用 swaggerdoc 插件:
// {app_root}/config/plugin.js exports.swaggerdoc = { enable: true, // 是否启用 package: 'egg-swagger-doc' // 指定包名称 }
再在 config 配置文件中添加 swaggerdoc 插件的配置信息:
// {app_root}/config/config.default.js exports.swaggerdoc = { dirScanner: './app/controller', // 配置自动扫描的控制器路径 apiInfo: { title: '接口文档', // 接口文档的标题 description: 'swagger 测试接口文档', // 接口文档描述 version: '1.0.0', // 接口文档版本 termsOfService: 'http://swagger.io/terms/', // 服务条件 contact: { email: 'sunjianfeng@csxiaoyao.com' // 联系方式 }, license: { name: 'Apache 2.0', url: 'http://www.apache.org/licenses/LICENSE-2.0.html' }, }, basePath: '/', // 配置基础路径 schemes: ['http', 'https'], // 配置支持的协议 consumes: ['application/json'], // 指定处理请求的提交内容类型 (Content-Type),如 application/json、text/html produces: ['application/json'], // 指定返回的内容类型,仅当 request 请求头中的(Accept)类型中包含该指定类型才返回 securityDefinitions: {}, // 配置接口安全授权方式 enableSecurity: false, // 是否启用授权,默认 false // enableValidate: true, // 是否启用参数校验,默认 true routerMap: false, // 是否启用自动生成路由(实验功能),默认 true enable: true // 默认 true }
参数的编写一共分为两大部分:controller 和 contract,在完成插件引入后,如果不修改默认配置,应用启动后,会自动扫描 app/controller 和 app/contract 下的文件。controller 为 api 的控制器,而 contract 下的文件为定义好的请求体和响应体。
控制器的注释分两块,每个控制器的第一个注释块必须包含 @controller 才能被解析为控制器,然后会逐个解析出控制器下包含的 api 注释。
/** * @controller HomeController */ class HomeController extends Controller { /** * @router get /index 路径 * @summary 接口的小标题信息 * @description 接口的描述信息 * @request query integer id 对参数id的描述 * @request query string name 对参数name的描述 * @response 200 indexJsonBody */ async index () { ... } }
而 contract 下则定义了常用的请求体和响应体,可以对格式进行约束。
const JsonBody = { code: { type: 'number', required: true, example: 0 }, message: { type: 'string', required: true, example: 'success' }, data: { type: 'Enum', required: true, example: [] }, } module.exports = { indexJsonBody: { ...JsonBody, data: { type: 'string', example: 'test' }, }, };
配置完后,执行 dev 脚本,即可打开 /swagger-ui.html
看到生成的文档。
$ npm run dev
swagger 有以下常用的注释:
@Controller {ControllerName} @Router {Mothod} {Path} @Request {Position} {Type} {Name} {Description} @Response {HttpStatus} {Type} {Description} @Deprecated @Description {Description} @Summary {Summary}
对于 swagger 注释参数详细信息,可以参考 https://www.npmjs.com/package/egg-swagger-doc,还可以在 swagger 编辑器中对照生成 https://editor.swagger.io。
本文转载自微信公众号「编程珠玑」,作者守望先生。转载本文请联系编程珠玑(ID:...
在之前文章《我是如何使用wireshark软件的》中介绍了wireshark的使用,提到了显...
公司简介 我们公司是蒂森克虏伯,是一家来自德国的多元化工业集团,其下属的电梯...
学习数据科学绝非易事。能找到一个可以分享代码、数据和想法的社区对我们的学习...
wagger 是开发中最常用的框架之一了,但 Swagger 本身又有很多不完善的地方,比...
作者 | 林青 来源 | 阿里技术公众号 随着 IoT 技术的快速发展,物联网设备产生的...
1. 接口描述 接口请求域名: cvm.tencentcloudapi.com 。 本接口 (ResetInstance...
简介 ES10是ECMA协会在2019年6月发行的一个版本,因为是ECMAScript的第十个版本...
操作场景 如果您需要使用创建的云服务器搭建一个对外展示的网站或者Web应用程序...
TOP云 12月25日讯,接近年末,米圈投资人也渐渐转向3字母叠 域名 投资,通过西数...