运用Swagger编写API文档
运用Swagger编写API文档
- 1 Swagger
- 1.1 什么是Swagger
- 1.2 SwaggerEditor安装与启动
- 1.3 编写示例
- 1.4 SwaggerUI环境搭建
1 Swagger
1.1 什么是Swagger
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要， swagger 就是一款让你更好的书写API文档的框架。
1.2 SwaggerEditor安装与启动
1）全局安装http-server
http-server是一个简单的零配置命令行http服务器
npm install ‐g http‐server
2）启动swagger-editor
cmd进入swagger-editor所在文件夹
http‐server swagger‐editor
浏览器打开： http://localhost:8080
1.3 编写示例
swagger: "2.0"
info:
version: 1.0.0
title: 物流模块 API
host: api.logistics.chen
basePath: /logistics
tags:
- name: area
description: 地区相关接口
- name: calculation
description: 计算方式相关接口
- name: channel
description: 渠道相关接口
- name: company
description: 货运公司相关接口
schemes:
- http
paths:
/area:
post:
tags:
- area
summary: 新增地区
parameters:
- in: body
name: body
description: 地区实体类
required: true
schema:
$ref: '#/definitions/Area'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
tags:
- area
summary: 返回地区列表
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiAreaListResponse'
/area/{areaId}:
put:
tags:
- area
summary: 根据ID修改地区
parameters:
- name: areaId
in: path
description: 地区ID
required: true
type: string
- in: body
name: body
description: 地区实体类
required: true
schema:
$ref: '#/definitions/Area'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
delete:
tags:
- area
summary: 根据ID删除地区
parameters:
- name: areaId
in: path
description: 地区ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
tags:
- area
summary: 根据ID查询地区
parameters:
- name: areaId
in: path
description: 地区ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiAreaResponse'
/area/search:
post:
tags:
- area
summary: 根据条件查询地区列表
parameters:
- in: body
name: body
description: 地区实体类
required: true
schema:
$ref: '#/definitions/Area'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiAreaListResponse'
/area/search/{page}/{size}:
post:
tags:
- area
summary: 根据条件查询地区列表 分页
parameters:
- name: page
in: path
description: 页码
required: true
type: integer
format: int32
- name: size
in: path
description: 页大小
required: true
type: integer
format: int32
- in: body
name: body
description: 地区实体类
required: true
schema:
$ref: '#/definitions/Area'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiAreaPageResponse'
/company:
post:
tags:
- company
summary: 新增货运公司
parameters:
- in: body
name: body
description: 货运公司实体类
required: true
schema:
$ref: '#/definitions/Company'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
tags:
- company
summary: 返回货运公司列表
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCompanyListResponse'
/company/{companyId}:
put:
tags:
- company
summary: 根据ID修改公司
parameters:
- name: companyId
in: path
description: 公司ID
required: true
type: string
- in: body
name: body
description: 公司实体类
required: true
schema:
$ref: '#/definitions/Company'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
delete:
tags:
- company
summary: 根据ID删除公司
parameters:
- name: companyId
in: path
description: 公司ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
tags:
- company
summary: 根据ID查询公司
parameters:
- name: companyId
in: path
description: 公司ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCompanyResponse'
/company/search:
post:
tags:
- company
summary: 根据条件查询公司列表
parameters:
- in: body
name: body
description: 公司实体类
required: true
schema:
$ref: '#/definitions/Company'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCompanyListResponse'
/company/search/{page}/{size}:
post:
tags:
- company
summary: 根据条件查询地区列表 分页
parameters:
- name: page
in: path
description: 页码
required: true
type: integer
format: int32
- name: size
in: path
description: 页大小
required: true
type: integer
format: int32
- in: body
name: body
description: 公司实体类
required: true
schema:
$ref: '#/definitions/Company'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCompanyPageResponse'
definitions:
Area:
type: object
properties:
id:
type: string
description: ID
name:
type: string
description: 地区名称
code:
type: string
description: 地区简码
ApiAreaResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/Area'
AreaList:
type: array
items:
$ref: '#/definitions/Area'
ApiAreaListResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/AreaList'
ApiAreaPageResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
properties:
total:
type: integer
format: int32
rows:
$ref: '#/definitions/AreaList'
Company:
type: object
properties:
id:
type: string
description: ID
name:
type: string
description: 公司名称
code:
type: string
description: 公司简介
ApiCompanyResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/Company'
CompanyList:
type: array
items:
$ref: '#/definitions/Company'
ApiCompanyListResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/CompanyList'
ApiCompanyPageResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
properties:
total:
type: integer
format: int32
rows:
$ref: '#/definitions/CompanyList'
ApiResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
1.4 SwaggerUI环境搭建
1.新建works文件夹，然后进入到 works目录，执行初始化命令：npm init ，出现如下信息，填的地方可以随便写，也可以不写
2. 解压swagger-ui-master.zip,将dist 文件夹复制到 works下
3. 安装express cd works>npm install express
4. 在works文件夹下创建index.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!');
});
5.然后启动，并运行查看，如上代码为3000端口，如有冲突请自行修改
cd works>node index.js // 启动命令
Example app listening on port 3000!
浏览器输入地址：http://127.0.0.1:3000/root/index.html
6.使用自己的api文档
works/dist/index.html下 修改
