用YAML写swagger Editor

学习yaml 可以看这篇阮一峰的博客写的很好 http://www.ruanyifeng.com/blog/2016/07/yaml.html

 

Yaml

每部分意义

 

swagger: '2.0'
info:
 description: >-
   This is a sample server Petstore server. You can find out more about    
   Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
    #swagger](http://swagger.io/irc/).     For this sample, you can use the api
   key `special-key` to test the authorization     filters.
 version: 1.0.0
 title: Swagger Petstore
 termsOfService: 'http://swagger.io/terms/'
 contact:
   email: [e-mail]
 license:
   name: Apache 2.0
   url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: petstore.swagger.io
basePath: /v2
tags:
 - name: User
   description: 用户模块接口
schemes:
 - http
paths:
 /User:
   post:
     tags:
       - User
     summary: Add a new pet to the store
     description: ''
     operationId: addPet
     consumes:
       - application/json
       - application/xml
     produces:
       - application/xml
       - application/json
     parameters:
       - in: body
         name: body
         description: Pet object that needs to be added to the store
         required: true
         schema:
           $ref: '#/definitions/Pet'
     responses:
       '405':
         description: Invalid input
     security:
       - petstore_auth:
           - 'write:pets'
           - 'read:pets'
   put:
     tags:
       - User
     summary: Update an existing pet
     description: ''
     operationId: updatePet
     consumes:
       - application/json
       - application/xml
     produces:
       - application/xml
       - application/json
     parameters:
       - in: body
         name: body
         description: Pet object that needs to be added to the store
         required: true
         schema:
           $ref: '#/definitions/Pet'
     responses:
       '400':
         description: Invalid ID supplied
       '404':
         description: Pet not found
       '405':
         description: Validation exception
     security:
       - petstore_auth:
           - 'write:pets'
           - 'read:pets'

 

swagger

表示版本号

info

头部说明

tags

name

模块名称

description

模块说明

schemes

Http请求

paths

/接口名

post

请求方式

tags

-User 对应上面tags里面的name

summary

接口说明

description

接口的具体说明

consumes

传递的参数格式选择

produces

返回的参数格式选择

parameters

参数

name

参数名称

in

传递的参数放在哪里

query

查询参数，例如/user。role=admin

path

路径参数，如/用户/id

header

头参数，如x-myheader:值

body

描述POST、PUT和补丁请求的主体的主体参数(参见描述请求主体)

form

表单参数——用于描述应用程序/x-www格式的请求的有效负载的各种各样的body参数，包括urlen编码和多部分/表单数据(后者通常用于文件上传)。

description

参数描述

required

参数是否是必须传递的

schema

参数格式

$ref: '#/definitions/Pet' 是引用 definitions下面的Pet模块

responses

'405'

返回的状态码如果是405

就会有一个描述

 

时间格式

    type: string
   format: date-time

Double格式

    type: integer
   format: double

LIst集合格式

  hospitals:
   type: array
   xml:
     name: hospital
     wrapped: true
   items:
     $ref: '#/definitions/Hospital'

Hospital是一个实体类

hospitals表示是一个Hospital实体类的集合,type 表示是arrayList集合, items是引用的哪个实体类