REST API をswaggerで定義する - 闘うITエンジニアの覚え書き

docker 使うのが楽

docker pull swaggerapi/swagger-editor
docker run -p 8888:8080 swaggerapi/swagger-editor

オンライン版
https://editor.swagger.io/

git clone https://github.com/swagger-api/swagger-ui.git

で 配下の dist をどっかWebサーバに配置する。

swagger: '2.0'
info:
  version: '2017-12-17T05:28:50Z'
  title: SampleApi1
schemes:
  - https
paths:
  '/books':
    get:
      produces:
        - application/json
      responses:
        '200':
          description: 200 response
#          schema:
#            type: "array"
#            items:
#              $ref: "#/definitions/BookModel"
          schema:
            type: "object"
            properties:
              items:
                title: items
                type: "array"
                items:
                  $ref: "#/definitions/BookModel"
    post:
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: BookParams
          in: body
          required: true
          schema:
            $ref: '#/definitions/BookParams'
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/CreatedBook'
  '/books/{id}':
    get:
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/BookModel'
    put:
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
        - name: BookParams
          in: body
          schema:
            # definitions参照する場合
            $ref: '#/definitions/BookModel'
            # 個別定義する場合
            #type: object
            #properties:
            #  isbn:
            #    title: isbn
            #    type: string
            #  title:
            #    title: title
            #    type: string
            #  price:
            #    title: price
            #    type: integer
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/Empty'
    delete:
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 response
          schema:
            $ref: '#/definitions/Empty'
definitions:
  Empty:
    type: object
    title: Empty Schema
  CreatedBook:
    type: object
    title: Created book
    properties:
      id:
        title: id
        type: string
  BookModel:
    type: object
    title: Book Model
    properties:
      id:
        title: id
        type: string
      isbn:
        title: isbn
        type: string
      title:
        title: title
        type: string
      price:
        title: price
        type: integer
  BookParams:
    type: object
    title: Parameters for book regist or update
    properties:
      isbn:
        title: isbn
        type: string
      title:
        title: title
        type: string
      price:
        title: price
        type: integer