OpenAPI Specification を利用してAPI仕様書を作成する

11289 ワード
OpenAPI ReDoc OpenAPI テキストリンク

概要

  • Web API の設計という本を読んでみて、APIのドキュメント作成に OSA（OpenAPI Specification）が取り上げられていたので触ってみた

OpenAPI Specificationとは

  • プログラミング言語に依存しない REST API 記述フォーマットのこと
  • OAI（OpenAPI Initiative）が推進しているフォーマット
  • 以前は Swagger Specificationと呼ばれていた
  • 以下のSwagger Editorのでも画面のようにREST APIの使用を yaml または json 形式で記述する

swaggerとは

  • OASを記述するための、オープンソースのツール。ドキュメント作成のためのEditorや、ドキュメントからコード自動生成するためのツールや、ドキュメント表示のためのUI等様々なツールを提供している

  • https://swagger.io/docs/specification/about/

ツール

OSAサンプル

petstore.yml
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: [email protected]
  license:
    name: Apache-2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: petstore.swagger.io
basePath: /v2
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user
    externalDocs:
      description: Find out more about our store
      url: 'http://swagger.io'
schemes:
  - http
paths:
  /pet:
    post:
      tags:
        - pet
      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'

~ 以下省略 ~

ドキュメントサンプル

その他のドキュメント生成ツール

Redoc

  • Swagger UI 同様、HTMLドキュメント生成を行うツールだが、Swagger UIよりもデザインが良く、使い勝手も良さそう

デモ画面

ドキュメント生成方法

$ npm install -g redoc-cli
$ redoc-cli bundle petstore.yml
  • 「redoc-static.html」が生成され、APIドキュメントを表示することができる。

その他参考