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

Posted at 2020-09-22

概要

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

OpenAPI Specificationとは

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

swaggerとは

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

ツール

https://swagger.io/tools/
- Swagger Editor
- Swagger Codegen
- Swagger UI

OSAサンプル

Swagger が提供しているサンプルプロジェクトから、実際に作成しているymlファイルを確認することができる
- https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml

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: 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: 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'

~ 以下省略 ~

ドキュメントサンプル

Swagger UI による実際に生成されたHTMLドキュメントのデモ画面をみることができる
- https://petstore.swagger.io/

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

Redoc

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

デモ画面

https://redocly.github.io/redoc/

ドキュメント生成方法

https://github.com/Redocly/redoc/blob/master/cli/README.md#usage
redoc-cliのインストールを行い、以下のコマンド実行することでymlファイルから静的ドキュメントを生成することができる

$ npm install -g redoc-cli
$ redoc-cli bundle petstore.yml

「redoc-static.html」が生成され、APIドキュメントを表示することができる。

その他参考

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up