运用swagger编写api文档
一.什么是swagger
随着互联网技术的发展,前后端技术在各自的道路上越走越远,他们之间的唯一联系变成了api接口,api接口文档编程了前后端人员的纽带,而swagger就是书写api文档的一款框架.
相关资源下载地址: https://download.csdn.net/download/zhixingwu/12008773
推荐: 也可以使用 showdoc来书写api文档. 官网: https://www.showdoc.cc/
二.SwaggerEditor的安装与启动
- 下载 swagger-editor.zip
- 解压swagger-editor
- 全局安装http-server(http-server是一个简单的零配置命令行http服务器)
npm install ‐g http‐server
- 启动swagger-editor
http‐server swagger‐editor
- 浏览器打开: http://localhost:8080
三.语法规则
1.固定字段
字段名 | 类型 | 描述 |
---|---|---|
swagger | string | 必需的。使用指定的规范版本 |
info | info Object | 必需的。提供元数据API |
host | string | 主机名或ip服务API |
basePath | string | API的基本路径 |
schemes | [string] | API的传输协议。 值必须从列表中:"http","https","ws","wss"。 |
consumes | [string] | 一个MIME类型的api可以使用列表。值必须是所描述的Mime类型 |
produces | [string] | MIME类型的api可以产生的列表。 值必须是所描述的Mime类型 |
paths | 路径对象 | 必需的。可用的路径和操作的API |
definitions | 定义对象 | 一个对象数据类型生产和使用操作 |
parameters | 参数定义对象 | 一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。 |
responses | 反应定义对象 | 一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应 |
externalDocs | 外部文档对象 | 额外的外部文档 |
summary | string | 什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符 |
description | string | 解释操作的行为 |
operationId | string | 独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定 |
deprecated | boolean | 声明该操作被弃用。 使用声明的操作应该没有。 默认值是false |
2.字段类型与格式定义
普通名字 | type | format | 说明 |
---|---|---|---|
integer | integer | int32 | 签署了32位 |
long | integer | int64 | 签署了64位 |
float | number | float | |
double | number | double | |
string | string | ||
byte | string | byte | base64编码的字符 |
binary | stirng | binary | 任何的八位字节序列 |
boolean | boolean | ||
date | string | date | 所定义的full-date- - - - - -RFC3339 |
datetime | string | date-time | 所定义的date-time- - - - - -RFC3339 |
password | stirng | password | 用来提示用户界面输入需要模糊 |
四.示例-城市API文档
swagger: '2.0'
info:
version: "1.0.0"
title: 基础模块-城市API
host: api.pcloud.com
basePath: /base
paths:
/city:
post:
summary: 新增城市
parameters:
-
name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 返回城市列表
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/{cityId}:
put:
summary: 修改城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
delete:
summary: 根据ID删除城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'
get:
summary: 根据ID查询城市
parameters:
- name: cityId
in: path
description: 城市ID
required: true
type: string
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityResponse'
/city/search:
post:
summary: 根据条件查询城市列表
parameters:
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityListResponse'
/city/search/{page}/{size}:
post:
summary: 城市分页列表
parameters:
- name: page
in: path
description: 页码
required: true
type: integer
format: int32
- name: size
in: path
description: 页大小
required: true
type: integer
format: int32
- name: body
in: body
description: 城市实体类
required: true
schema:
$ref: '#/definitions/City'
responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiCityPageResponse'
definitions:
City:
type: object
properties:
id:
type: string
description: ID
name:
type: string
description: 城市名称
ishot:
type: string
description: 是否热门
ApiResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
ApiCityResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/City'
CityList:
type: array
items:
$ref: '#/definitions/City'
ApiCityListResponse:
type: object
properties:
flag:
type: boolean
description: 是否成功
code:
type: integer
format: int32
description: 返回码
message:
type: string
description: 返回信息
data:
$ref: '#/definitions/CityList'
ApiCityPageResponse:
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/CityList'
五.批量生成API文档
使用<<黑马程序员代码生成器>>自动生成所有标的yml文档,自动生成的文档中类型均为string ,我们这里需要再对类型进行修改即可.
步骤:
(1)执行建表脚本
(2)使用《黑马程序员代码生成器》生成脚本(HeimaCodeUtil_V2.4_64.zip)
六.swaggerUI
SwaggerUI是用来展示Swagger文档的界面,以下为安装步骤
(1)在本地安装nginx
(2)下载SwaggerUI源码 https://swagger.io/download-swagger-ui/
(3)解压,将dist文件夹下的全部文件拷贝至 nginx的html目录
(4)启动nginx
(5)浏览器打开页面 http://localhost即可看到文档页面
(6)将编写好的yml文件也拷贝至nginx的html目录,这样我们就可以加载我们的swagger文档了
运用swagger编写api文档的更多相关文章
- SpringBoot系列: 使用 Swagger 生成 API 文档
SpringBoot非常适合开发 Restful API程序, 我们都知道为API文档非常重要, 但要维护好难度也很大, 原因有: 1. API文档如何能被方便地找到? 以文件的形式编写API文档都有 ...
- swagger在线api文档搭建指南,用于线上合适么?
在上一篇文章中,我们讲解了什么是 api,什么是 sdk: https://www.cnblogs.com/tanshaoshenghao/p/16217608.html 今天将来到我们万丈高楼平地起 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...
- 【WebAPI No.4】Swagger实现API文档功能
介绍: Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为 ...
- springboot+mybatis-puls利用swagger构建api文档
项目开发常采用前后端分离的方式.前后端通过API进行交互,在Swagger UI中,前后端人员能够直观预览并且测试API,方便前后端人员同步开发. 在SpringBoot中集成swagger,步骤如下 ...
- Swagger实现API文档功能
介绍: wagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什 ...
- springboot利用swagger构建api文档
前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.本文简单介绍了在项目中集成swagger的方法和一些常见问题.如果想深入分析项目源码,了解更多内容,见参考资料. S ...
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)
前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
随机推荐
- pt-align的用法简要记录
pt-align的用法简要记录 1.pt-align 功能:将其它工具的输出按列对齐用法:pt-align [FILES]如果没有指定文件,则默认读取标准输入的内容. 2.例如: [root@dbte ...
- excel解决日常问题记录
=MOD(ROW(),2)和=TEXT(B2487-B2486,"[h]:mm:ss"),我利用excel分析出了延迟的数据 比较2个字符串是否一样:=EXACT(A2,F2) 公 ...
- PHP基础教程探讨一些php编程性能优化总结
兄弟连PHP培训 小编最近在做php程序的性能优化,一些经过测试后发现的东西就先记录下来,以备后用. 首先对于一些反应慢的操作或页面要跟踪处理一下,可以使用webGrind的方式看一下主要问题出在 ...
- Luogu P4550 收集邮票
题目链接:Click here Solution: 本题直接推价格似乎很难,考虑先从购买次数入手 设购买次数\(g(i)\)为当前有\(i\)种不同的邮票,要买到\(n\)种的期望购买次数 可以由期望 ...
- [Noip模拟题]宠物之战senso
Description 众所周知,moreD的宠物已经被moreD奴役得体无完肤.这只宠物实在忍无可忍,把自己每天走魔法树的经历告诉了 自己的宠物.同时他还说明了自己爬树是多么地慢,以至于moreD每 ...
- android 文件保存到应用和sd卡中
<span style="font-size:18px;">1.权限添加 <uses-permission android:name="android. ...
- pycharm selenium 安装firefox驱动和Google驱动教程
一.下载Firefox浏览器或Google浏览器 下载渠道有很多,直接下载最新版的就可以了. 二.下载驱动 Firefox驱动 地址:https://github.com/mozilla/geckod ...
- Json-lib 的学习笔记
json 按照我的理解来说,就是一个字串表,可以用来表示对象的字符串,也可以用来表示数组.它比 xml 文件节省了很多标签的内容. 关于什么是 json,在这里我们就不过多介绍了. Json-lib ...
- pymysql(一)检索、增加、更新、删除数据
(一) SELECT 检索数据 代码如下: import pymysql '''pymysql使用指南host = '127.0.0.1'回送地址,指本地机port = 3306MySQL的默认端口 ...
- 错误1919,配置ODBC数据源MS Access Database时发生错误ODEC错误
WIN7 64位旗舰版安装OFFICE2003 提示:“错误1919,配置ODBC数据源MS Access Database时发生错误ODEC错误” 在64位系统上,32位软件的注册表的信息不是直接在 ...