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

## 概要

- [Web API の設計](https://www.amazon.co.jp/API%E3%81%AE%E8%A8%AD%E8%A8%88-Programmers-SELECTION-Arnaud-Lauret/dp/4798167010)という本を読んでみて、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
 

```yml: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ドキュメントを表示することができる。

![e3642a4a-7e0b-4127-8a56-7408370969f5.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/366054/06aad667-efed-73b0-86c3-a8968003965e.png)


## その他参考
- https://qiita.com/halhorn/items/e47673eecc4a01ffb3a0
- https://www.wantedly.com/companies/openwork/post_articles/184788
- https://qiita.com/jonghyo/items/f1f56251df12eee92e64
- https://qiita.com/buzztaiki/items/6b04d735f28e00b8b574