用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是引用的哪個實體類