nodejs自动生成接口文档_使用Swagger快速生成RESTFUl-API接口文档

The Best APIs are Built with Swagger Tools

概述

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单

官网：http://swagger.io/

RESTful

REST是Roy Thomas Fielding博士于2000年提出来的一种万维网软件架构风格，目的是便于不同软件/程序在网络中互相传递信息，从其诞生之日开始，它就因其可扩展性和简单性受到越来越多的架构师和开发者们的青睐

• 概念

资源(Resource)：系统上的所有事物都被抽象为资源(一篇文章，一张照片，一段语音)

集合(Collection)：一组资源的合辑称为集合(几篇文章，几张照片)

路径(Endpoint)：路径又称”终点“，表示API的具体网址(每个网址代表一种资源)

• 特点

RESTful定义，CRUD操作分别对应相应的HTTP方法

GET(SELECT)：从服务器获取资源

POST(CREATE)：在服务器新建一个资源

PUT(UPDATE)：在服务器更新资源

PATCH(UPDATE)：在服务器更新资源

DELETE(DELETE)：从服务器删除资源

简单的介绍了RESTful的一些基本概念，不做过多赘述

编写文档

Swagger可以使用JSON或者YAML来编写API文档，并且swagger 官网提供了 swagger编辑器，你可以在这个编辑器中创建或导入文档，并在交互式环境中浏览它

编辑器地址为： http://editor.swagger.io/#/

• JSON格式

大家对JSON的文件格式都比较熟悉，这里就不过多解析了，着重介绍如下这种写法

• YAML格式

swagger: "2.0" # 表示当前swagger的版本

info: #swagger描述信息

title: Sample API

description: API description in Markdown.

version: 1.0.0

host: api.example.com

basePath: /v1

schemes:

- https

paths: # API路径信息

/users:

get:

summary: Returns a list of users.

description: Optional extended description in Markdown.

produces:

- application/json

responses:

200:

description: OK

更多的定义内容可以查看：https://swagger.io/docs/specification/about/更多更详细的YALM教程可以查看大佬的教程YALM教程：http://www.ruanyifeng.com/blog/2016/07/yaml.html

Swagger工具

• Swagger Core

Swagger-core 是 Swagger的Java 实现. 是整个swagger工具的核心实现. Swagger Core是使用Java编程实现的.

• Swagger Codegen

提供了根据swagger的接口定义文件(yaml形式), 直接生产相应的代码, 以一种命令行工具的形式

• Swagger Editro

yaml或JSON定义简单的接口格式, 然后通过 Swagger-codergen 就可以自动生成相应的服务端 和 客户端的调用代码了，并可下载使用

Swagger Editro示意图

不同语言工具集合：https://github.com/APIDevTools/swagger-parser#swagger-parser

搭建Swagger服务器

• 使用koa搭建server

一个简单的koa server

• 下载Swagger官方Demo

下载地址：https://github.com/swagger-api/swagger-ui(有可能比较慢，下载慢的话耐心等一等)

• 新建文件夹放置刚才下载的官方Demo

解压swagger-ui-master.zip，复制dist文件夹内容放置到新建文件夹中

• 修改server代码

修改server

这时候就可以访问3000端口

本地Swagger服务器

• 替换成自己的接口文档

我们可以通过http://editor.swagger.io/编写自己的代码，并下载JSON文件到新建文件夹，并修改index.html将demo切换为自己编写的Swagger文件

下载JSON文件

修改为自身编写的接口

相关资源

Swagger相关工具

swagger-bootstrap-ui：https://github.com/xiaoymin/swagger-bootstrap-ui/blob/master/README_zh.md

smock:https://www.npmjs.com/package/jdcfe-smock

接口管理

https://github.com/YMFE/yapi

补充中...

小结

通过使用Swagger，在开发过程中能较好的实现同步api文档，从而避免了后端代码更新但是前端文档为更新而导致的种种问题，而且支持的语言比较广泛，能较好的应用在不同的项目中

参考资料

https://juejin.im/post/5964ce816fb9a06bb21abb23#heading-15

https://www.jianshu.com/p/d6626e6bd72c