一.什么是swagger

随着互联网技术的发展,前后端技术在各自的道路上越走越远,他们之间的唯一联系变成了api接口,api接口文档编程了前后端人员的纽带,而swagger就是书写api文档的一款框架.

官网: https://swagger.io/

相关资源下载地址: https://download.csdn.net/download/zhixingwu/12008773

推荐: 也可以使用 showdoc来书写api文档. 官网: https://www.showdoc.cc/

二.SwaggerEditor的安装与启动

  1. 下载 swagger-editor.zip
  2. 解压swagger-editor
  3. 全局安装http-server(http-server是一个简单的零配置命令行http服务器)

    npm install ‐g http‐server

  4. 启动swagger-editor

    http‐server swagger‐editor

  5. 浏览器打开: 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文档的更多相关文章

  1. SpringBoot系列: 使用 Swagger 生成 API 文档

    SpringBoot非常适合开发 Restful API程序, 我们都知道为API文档非常重要, 但要维护好难度也很大, 原因有: 1. API文档如何能被方便地找到? 以文件的形式编写API文档都有 ...

  2. swagger在线api文档搭建指南,用于线上合适么?

    在上一篇文章中,我们讲解了什么是 api,什么是 sdk: https://www.cnblogs.com/tanshaoshenghao/p/16217608.html 今天将来到我们万丈高楼平地起 ...

  3. 在ASP.NET Core Web API上使用Swagger提供API文档

    我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...

  4. Core Web API上使用Swagger提供API文档

    在ASP.NET Core Web API上使用Swagger提供API文档   我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...

  5. 【WebAPI No.4】Swagger实现API文档功能

    介绍: Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为 ...

  6. springboot+mybatis-puls利用swagger构建api文档

    项目开发常采用前后端分离的方式.前后端通过API进行交互,在Swagger UI中,前后端人员能够直观预览并且测试API,方便前后端人员同步开发. 在SpringBoot中集成swagger,步骤如下 ...

  7. Swagger实现API文档功能

    介绍: wagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什 ...

  8. springboot利用swagger构建api文档

    前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.本文简单介绍了在项目中集成swagger的方法和一些常见问题.如果想深入分析项目源码,了解更多内容,见参考资料. S ...

  9. 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)

    前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...

随机推荐

  1. pt-align的用法简要记录

    pt-align的用法简要记录 1.pt-align 功能:将其它工具的输出按列对齐用法:pt-align [FILES]如果没有指定文件,则默认读取标准输入的内容. 2.例如: [root@dbte ...

  2. excel解决日常问题记录

    =MOD(ROW(),2)和=TEXT(B2487-B2486,"[h]:mm:ss"),我利用excel分析出了延迟的数据 比较2个字符串是否一样:=EXACT(A2,F2) 公 ...

  3. PHP基础教程探讨一些php编程性能优化总结

      兄弟连PHP培训 小编最近在做php程序的性能优化,一些经过测试后发现的东西就先记录下来,以备后用. 首先对于一些反应慢的操作或页面要跟踪处理一下,可以使用webGrind的方式看一下主要问题出在 ...

  4. Luogu P4550 收集邮票

    题目链接:Click here Solution: 本题直接推价格似乎很难,考虑先从购买次数入手 设购买次数\(g(i)\)为当前有\(i\)种不同的邮票,要买到\(n\)种的期望购买次数 可以由期望 ...

  5. [Noip模拟题]宠物之战senso

    Description 众所周知,moreD的宠物已经被moreD奴役得体无完肤.这只宠物实在忍无可忍,把自己每天走魔法树的经历告诉了 自己的宠物.同时他还说明了自己爬树是多么地慢,以至于moreD每 ...

  6. android 文件保存到应用和sd卡中

    <span style="font-size:18px;">1.权限添加 <uses-permission android:name="android. ...

  7. pycharm selenium 安装firefox驱动和Google驱动教程

    一.下载Firefox浏览器或Google浏览器 下载渠道有很多,直接下载最新版的就可以了. 二.下载驱动 Firefox驱动 地址:https://github.com/mozilla/geckod ...

  8. Json-lib 的学习笔记

    json 按照我的理解来说,就是一个字串表,可以用来表示对象的字符串,也可以用来表示数组.它比 xml 文件节省了很多标签的内容. 关于什么是 json,在这里我们就不过多介绍了. Json-lib ...

  9. pymysql(一)检索、增加、更新、删除数据

    (一)  SELECT 检索数据 代码如下: import pymysql '''pymysql使用指南host = '127.0.0.1'回送地址,指本地机port = 3306MySQL的默认端口 ...

  10. 错误1919,配置ODBC数据源MS Access Database时发生错误ODEC错误

    WIN7 64位旗舰版安装OFFICE2003 提示:“错误1919,配置ODBC数据源MS Access Database时发生错误ODEC错误” 在64位系统上,32位软件的注册表的信息不是直接在 ...