用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: apiteam@swagger.io
  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是引用的哪个实体类