如何搭建Swagger接口文档
来源:互联网 发布:linux进入单用户模式 编辑:程序博客网 时间:2024/06/07 03:51
Swagger是规范RESTful API服务的语言或者说工具,不仅可以用来定义接口,还可以测接口,一举两得。
我不知道这个工具的流行程度如何,至少我知道的是网上的中文资料很少,也没有如何在实际中使用起来的教程。经过一两天的研究,总结一个简单的搭建手册。
Swagger的核心工具主要为三个:
- Swagger-UI:API展示和测试页面
- Swagger-Editor:所见即所得式编辑工具
- Swagger-Codegen: 利用代码直接生成规范文档的工具
Swagger的规范文档是用yaml文件或者json文件来表述的,比如:
// yaml语法 swagger: "2.0"info: version: "1.0.0" title: "Netease Seasons API" description: "Netease seasons api docs" termsOfService: "http://helloreverb.com/terms/" contact: name: "野蛮的小小芬" email: "Yecao@163.com" license: name: "MIT" url: "http://opensource.org/licenses/MIT"host: "m.siji.163.com"schemes: - "http"consumes: - "application/json"produces: - "application/json" - "application/xml"paths: /index.json: get: tags: - "Homepage data" description: "get the productList" operationId: "getIndex" produces: - "application/json" responses: 200: description: "aqi response" default: description: "unexpected error"
用swagger-ui对应生成的页面是这样的:
使用Swagger来约定接口有两种方式:
- 第一种,在编辑器中写好文档,然后用Swagger-ui工具来展示;
- 第二种,在后端代码中按照约定的方式写上一些注释,使用Swagger-codegen自动扫描生成文档。
至于第二种方式,我也看了点网上的资料,但是后端的东西真的不懂,我就抛弃了。本文主要讲讲第一种方式,也是在前后端分离,并行开发的趋势下比较适用的。下面一步一步地说明如何搭建一个Swagger项目。
- 新建一个项目,运行
npm init
初始化package.json
。如果你的环境还没有node
的话,麻烦先安装一下node
,npm
命令自然就可以用了; - 运行
npm install swagger -g --save-dev
安装Swagger包; - 在项目根目录下,新建一个
api/swagger/swagger.yaml
,复制一个有效的yaml
内容进来,为下一步做准备; - 运行
Swagger project edit
,此时会自动打开一个swagger编辑窗口,读取的内容就是上一步中的yaml文件; - 尝试修改编辑窗口的内容,此时右侧会及时修改更新,而且
api/swagger/swagger.yaml
也会跟着自动更新 - 下载Swagger-ui,拷贝dist文件夹中的代码到根目录下新建的public文件夹;
由于swagger-ui不能本地运行,借助node的express创建一个服务,在根目录下创建
index.js
,代码如下:// 先安装依赖的express,opn包var express = require('express');var app = express(); var opn = require('opn'); app.listen(3000, function () { opn('http://localhost:3000/api-doc'); console.log('App listening on port 3000!');});app.use('/api-doc', express.static('public'));
运行
node index.js
会启用swagger-ui功能,自动打开api展示页面,但是页面是默认的官网上的东西;- 将
api/swagger
文件夹下的/swagger.yaml
文件复制到public文件夹下,打开public/index.html,在脚本中修改url为'./swagger.yaml'
,刷新浏览器,即可看到我们的内容 如何将swagger-editor文件的变化实时反馈到swagger-ui上,运行
npm install gulp -g --save-dev
安装gulp包,在根目录下新建gulpfile.js
,代码如下://记得先安装好依赖var gulp = require('gulp');var yaml = require('js-yaml');var path = require('path');var fs = require('fs');// 建立api/swagger的swagger.yaml到public下的swagger.yaml联系gulp.task('swagger', function(){ var doc = yaml.safeLoad(fs.readFileSync(path.join(__dirname, './api/swagger/swagger.yaml'))); fs.writeFile(path.join(__dirname, './public/swagger.yaml'), JSON.stringify(doc,null,' '));});// 实时更新gulp.task('default', function(){ gulp.watch('./api/swagger/swagger.yaml',['swagger']);})
到此,整个项目的依赖如下,都写在package.json里面,顺便也设置了npm的script:
{ "name": "api-docs", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "start": "node index.js", "swagger": "swagger project edit", "gulp": "gulp" }, "repository": { "type": "git", "url": "git+https://github.com/swagger-api/swagger-ui.git" }, "author": "", "license": "ISC", "devDependencies": { "express":"^4.15.2", "swagger":"0.7.5", "gulp":"3.9.1", "js-yaml":"3.8.3", "opn":"5.0.0" }, "bugs": { "url": "https://github.com/swagger-api/swagger-ui/issues" }, "homepage": "https://github.com/swagger-api/swagger-ui#readme"}
如果是多人协作的项目,创建一个git仓库,进行版本管理,使得接口文档的统一;
新建
README.md
,添加使用说明:## api-docs master分支是项目模板,一个项目开出一个分支来写接口文档此项目主要用来定义开发过程中的前后端接口定义接口是用yaml或者json文件来写的,规范请参考[OpenAPI使用说明](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)使用方式:1. npm install 安装需要的包2. npm start 开启swagger ui,测接口3. npm run swagger 打开编辑api窗口4. npm run gulp 实时监听swagger editor的变化到swagger ui5. npm run help 可以查看openAPI文档
如有不正确之处,欢迎指正!
作者:野草 20170505 首发地址
参考资料:
- Swagger官网-如何起步
- Swagger官网文档
- Swagger论坛
- Youtobe视频 Swagger: How to Create an API Documentation
- 使用Swagger插件丰富增强RESTful服务
- Swagger - 前后端分离后的契约
- 使用Swagger描述REST风格的API
- Swagger与SpringMVC项目整合
- Swagger初探
- app后端开发一:swagger-ui教程-构建api接口文档工具
- swagger ui教程,API文档生成神器
- Java
Documenting a REST API with Swagger and Spring MVC
0 0
- 如何搭建Swagger接口文档
- 用Swagger生成接口文档
- 使用Swagger,Swagger-UI生成REST API接口文档
- Swagger+Spring mvc生成Restful接口文档
- Swagger+Spring mvc生成Restful接口文档
- swagger实用接口文档生成框架
- swagger 生成 PHP restful API 接口文档
- Swagger+Spring mvc生成Restful接口文档
- swagger 生成 PHP restful API 接口文档
- springmvc 配置swagger ui 生成接口文档
- swagger+springmvc接口在线文档完美整合
- .使用Swagger导出rest接口文档
- 如何使用 Grape-Swagger 生成 API 文档
- swagger-ui教程-构建api接口文档工具
- springmvc集成swagger实现接口文档自动化生成
- spring-boot集成springfox(Swagger) (ApiDoc接口文档)
- swagger和springmvc结合自动生成api接口文档
- springmvc集成swagger实现接口文档自动化生成
- 练习 1-20 编写程序 detab,将输入中的制表符替换成适当数目的空格,使空格充满到 下一个制表符终止位的地方。
- 图片上传并异步提交
- TCP/IP、Http、Socket的区别
- Matlab获取新浪财经实时行情
- Hadoop(三) 大数据离线计算与实时计算
- 如何搭建Swagger接口文档
- 发送到受限的广播地址255.255.255.255失败的问题
- 排序算法的性能分析
- python连接oracel数据库,提取数据后制图并通过邮件发送
- jQ基础 类样式的几种
- CornerStone的使用
- TIOBE Index for April 2017(2017年04月编程语言排行榜)
- 【MySQL】MySQL关键字作为列名表名的处理方式
- Hibernate映射主键属性