1网址：
https://swagger.io/docs/specification/2-0/basic-structure/?_ga=2.9202677.1728138275.1595821745-29477687.1594714422
2基本结构：
2.1Metadata
#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
2.2Info
#必要字段！描述API接口信息的元数据
2.3BaseUrl
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
2.4MIME types
#接口接受和返回的数据类型格式
2.5Paths
#必要字段!定义可有可操作的API
2.6Parameter
#请求参数
2.7Responses
2.8Models
可重复使用代码
2.9Authentication
3demol
#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: '2.0'
#必要字段！描述API接口信息的元数据
info:
#接口标题
title: swagger说明文档
#接口文档的描述
description: 学习Swagger
#版本号
version: 2.0.0
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: 127.0.0.1
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
basePath: /userapi
#标签组
tags:
- name: User
description: 用户模块接口
#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
- http
- https
#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性
#方便swagger-ui测试，先不限制请求格式：浏览器请求默认没有该头信息"Content-Type":"application/json"出现415
#接口能消费的数据类型格式，在postman测试没问题，在swagger-ui界面测试因为默认没有这个content-type请求头所以先取消，正式开发前端人员会写死
#consumes:
# - application/json
#接口返回的数据类型格式
produces:
- application/json
#必要字段!定义可有可操作的API
paths:
/users:
#必要字段!定义HTTP操作方法，必须是http协议定义的方法
get:
#接口概要
summary: 查询用户列表
#接口描述
description: 查询出所有用户的所有信息
#接口方法名
operationId: getUsers
#标签，方便快速过滤出User相关的接口
tags:
- User
#返回值描述，必要字段
responses:
#返回的http状态码
200:
description: 所有用户信息或者用户的集合信息
#描述返回值
schema:
$ref: '#/definitions/UsersResponse'
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
$ref: '#/definitions/ExceptionResponse'
#针对于同一个url定义两个不同的方法，表示两个接口
post:
#接口概要
summary: 新增一个用户
#接口描述
description: 新增一个用户
operationId: addUser
#标签，方便快速过滤出User相关的接口
tags:
- User
#请求参数
parameters:
#参数key
- name: user
#传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
#body表示http头承载参数(body只能有一个,有body不能在有其他的)
in: body
#参数描述
description: 新增用户信息
#参数是否必要，默认false
required: true
schema:
$ref: '#/definitions/User'
responses:
#返回的http状态码
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
$ref: '#/definitions/ '
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
$ref: '#/definitions/ExceptionResponse'
/query:
get:
summary: 根据用户id查询用戶信息
description: 查询用戶信息
operationId: getUser
tags:
- User
parameters:
- name: id
in: query
description: 根据id查询用戶信息，是唯一标识
required: true
type: integer
responses:
200:
description: 用户的信息
schema:
$ref: '#/definitions/User'
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
$ref: '#/definitions/ExceptionResponse'
/user/{id}:
#{id}表示id为请求参数，例如/users/1,/users/2都是对该API的请求，此时id即为１和2
#上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型in为path
#http定义的delete方法,删除一个资源
delete:
summary: 删除用户
description: 删除某个用户的信息，被删除的用户将无法登陆
operationId: deleteUser
parameters:
- name: id
in: path
type: integer
required: true
description: 用户的唯一标示符
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
$ref: '#/definitions/SuccessResponse'
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
$ref: '#/definitions/ExceptionResponse'
#http定义的put方法，表示修改一个资源
put:
summary: 用户信息修改
description: 修改用户信息(用户名别名)
operationId: updateUser
parameters:
- name: id
in: path
description: 用户名,要修改的数据的唯一标识符
required: true
type: integer
- name: user
in: body
description: 新的用户信息
required: true
type: string
schema:
$ref: '#/definitions/User'
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果 返回true表示执行成功
schema:
$ref: '#/definitions/SuccessResponse'
default:
#描述错误信息
description: 操作异常,执行失败.返回信息描述错误详情
schema:
$ref: '#/definitions/ExceptionResponse'
definitions:
User:
#值类型
type: object
#定义属性
properties:
#属性名
userId:
#参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
type: integer
#描述
description: 用户的唯一id
userName:
type: string
description: 用户名
gender:
type: string
description: 性別
age:
type: integer
format: int32
description: 年齡
dateOfBirth:
type: string
format: date
description: 生日
AddUserRequest:
#值类型
type: object
#定义属性
properties:
#属性名
userName:
type: string
description: 用户名
gender:
type: string
description: 性別
age:
type: integer
format: int32
description: 年齡
dateOfBirth:
type: string
format: date
description: 生日
UsersResponse:
properties:
users:
description: 返回的user列表
#针对array,每个条目的格式,type定义为array．必要填写items
type: array
items:
#引用在definitions下定义的Users
$ref: "#/definitions/User"
ExceptionResponse:
type: object
properties:
code:
type: string
description: 错误码
msg:
type: string
description: 错误信息
SuccessResponse:
type: object
properties:
status:
#类型
type: boolean
#描述
description: 是否成功