yaml是一种配置是语言，大小写敏感，使用缩进代表层级关系，不能使用tab键，相同层级之间要求左边缩进对齐即可。
1，#代表注释说明
2， $ref: '#/definitions/Student' 表示定义的模型参数，一般在yaml接口的最后有个definition：Sudent代表模型
3，在接口声明中有路径参数的必须用'/student/{age}'引起来
如下是一个简单的接口声明定义swagger文档：
swagger: '2.0'
info:
description: >-
这是我的关于学生的接口文档Swagger
version: 1.2.0#版本号
title: 我的yaml
#服务支持的协议
schemes:
- https
#basePath，完整的访问路径为basePath + paths
basePath: /rest#根路径
paths:
/student/add: #完整的rest接口请求路径为/rest/student/add
#请求方式
post:
tags:
- Student#用于代码生成，声明方法所在类的名称
summary: 学生# 进行解释说明信息
description: 查询操作列表 描述
operationId: addStudent# 用于代码生成，声明方法名称
consumes: # 定义输入body的参数格式，还支持application/text，json，plat等
- application/json
produces: # 声明返回xml数据格式
- application/json
parameters:
-in: body#参数类型，还支持header，cookie，path，query等类型
name: body
description: 描述信息
required: true#参数是否必须，必须参数要显示声明为true，默认四是false
schema:
$ref: '#/definitions/Student' #模型参数
responses:
'401':
description: Invalid input
put:
tags:
- putStudent
summary: Update an existing student
description: ''
operationId: updateStudent
consumes:
- application/json
produces:
- application/json
parameters:
-in: body
name: body
description: 描述信息
required: true
schema:
$ref: '#/definitions/Student'
responses:
'400':
description: Invalid ID supplied
'404':
description: student not found
'405':
description: Validation exception
/student/findById:
get:
tags:
- Student
summary: Finds student by id
description: 描述信息
operationId: findstudentsById
produces:
- application/json
parameters:
-name: id
in: query
description: 描述信息
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Student'
'400':
description: Invalid status value
'/student/{age}':
get:
tags:
- Student
summary: Find student by age
description: 描述 信息
operationId: getStudentByAge
produces:
- application/json
parameters:
-name: age#声明为路径参数{age}跟这里的age要保持一致
in: path
description: 描述信息
required: true
type: integer
format: int64
responses:
'200':
description: successful operation
schema:
type: string
'400':
description: Invalid
'404':
description: student not found
definitions:
Student:
description: 学生
properties:
id:
description: ID
type: integer
name:
description: 学生名称
type: string
age:
description: 学生年龄
type: integer
编辑yaml接口之后可以现在http://editor.swagger.io/ 在线编辑swagger文档里面进行校验是否有缩进或者其他方面的错误
每天进步一点点
网友评论