Sawgger2 接口在线化文档生成教程

最新推荐文章于 2024-08-04 20:07:48 发布

loa_loa

最新推荐文章于 2024-08-04 20:07:48 发布

阅读量1.3k

点赞数

分类专栏：开源框架

本文链接：https://blog.csdn.net/loa_loa/article/details/106023548

版权

开源框架专栏收录该内容

11 篇文章 0 订阅

订阅专栏

前言

在做前后端分离的项目过程中，后端的接口文档更新维护的工作量很大。开发过程中接口发生变更，不仅要修改接口代码，还需要及时的修改接口文档。传统接口文档都是用word或excel进行记录编辑，而且还需要配合接口调用工具或到浏览器中进行接口的调用测试。这时候使用这套可视化，规范化的自动接口生成文档工具就会更加方便开发测试了。在工具页面中可以直接填写输入参数进行接口调用，不用再自己复制url链接去测试接口了。

总体思路

在swagger-editor中编写好了api文档，再放到swagger-ui中去预览，同时进行调用测试。

具体实现

一、sawgger editor编辑

1.swagger-editor 环境搭建

（1）安装node、npm、http-server

（2）从官网 https://github.com/swagger-api/swagger-editor 下载swagger editor并解压到任意文件夹

（3）cmd命令行cd到swagger editor解压路径，然后输入 http-server 命令显示启动成功

（默认为8080端口，修改端口运行命令 http-server –p 端口号）

（4）访问： http://127.0.0.1:8080

2.成功运行sawgger editor后，在左侧代码栏内进行编辑，右侧可以看效果也可以进行接口的调试

接口测试：右侧展示区内点击“Try this operation”按钮，输入参数并点击“Send Request”即可看到接口调用结果

3.编辑完成后下载json文件（生成文件swagger.json，后续需要放到展示的前端项目中）

二、sawgger UI展示

1.swagger-ui 环境搭建

（1）进入官网下载ui项目，并解压

https://github.com/swagger-api/swagger-ui/tree/2.x

（2）进行nodejs配置

mkdir node_app 新建node_app文件夹，

cd node_app 初始化node，输入好信息后会自动创建package.json文件

npm init 初始化命令，出现如下信息，填的地方可以随便写，也可以不写

（3）swagger-ui中的dist文件夹拷贝到node_app下：

（4）安装express

npm install express 如果出错可以去nodejs安装目录进行安装

（5）创建index.js

echo.>index.js 创建index.js

并将如下代码写入该js中:

var express = require('express');

var app = express();

app.use('/root', express.static('dist'));

app.get('/', function (req, res) {

  res.send('Hello World!');

});



app.listen(3000, function () {

  console.log('Example app listening on port 3000!');

});

2.更新json文件

（1）找到项目的dist文件夹内的index.html代码文件

（2）更新代码文件中json的url

url = "http://petstore.swagger.io/v2/swagger.json"; --> url = "/root/swagger.json";

（3）将Sawwger Editor中生成的swagger.json文件，放置index.html同级路径下

（每当接口有所更新，则需要重新生成该文件）

3.运行sawgger UI进行展示

（1）cmd命令框转到sawwger ui项目所在的路径，执行命令node index.js 运行项目

（2）浏览器输入地址 http://127.0.0.1:3000/root/index.html 即可运行查看（index.js中代码为3000端口，可自行修改）

*注：swagger-editor参数详情

Swagger API Spec包含以下部分：

swagger，指定swagger spec版本，2.0
info，提供API的元数据
tags，补充的元数据，在swagger ui中，用于作为api的分组标签
host，主机，如果没有提供，则使用文档所在的host
basePath，相对于host的路径
schemes，API的传输协议，http，https，ws，wss
consumes，API可以消费的MIME类型列表
produces，API产生的MIME类型列表
paths，API的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容：
- tags，操作的标签
- summary，短摘要
- description，描述
- externalDocs，外部文档
- operationId，标识操作的唯一字符串
- consumes，MIME类型列表
- produces，MIME类型列表
- parameters，参数列表
  - name，名字
  - description，描述required，是否必须
  - in，位置
    - Path
    - Query
    - Header
    - Body
    - Form
  - （对于Body类型的参数）
    - schema，数据类型，可以详细描述，也可以引用definition部分定义的schema
  - （对于Body类型以外的参数）
    - type，类型
    - format，数据格式
    - allowEmptyValue，是否允许空值
    - items，对于Array类型
    - collectionFormat，对于Array类型
    - default，缺省值-默认值
- responses，应答状态码和对于的消息的Schema
- schemes，传输协议
- deprecated，不推荐使用
- security，安全
definitions，定义API消费或生产的数据类型，使用json-schema描述，操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema
parameters，多个操作共用的参数
responses，多个操作共用的响应
securityDefinitions，安全scheme定义
security，安全声明
externalDocs，附加的外部文档