ゼロからはじめるOpen API

24 7月, 2020

イントロ

RESTful APIをつくるにあたって、昨今はOpen APIを使うのが常識となっています

しかし、とても早いスパンで更新され、開発されてきたため、未だ導入できていない、もしくはこれから導入しようという方も多いのではないかと思います

そこで、自分の備忘録を兼ねてこの記事ではOpen APIの始め方を紹介していきます

Open APIとは

すでに知っている方は読み飛ばしてください

元々はSwaggerという名前のプロジェクトでしたが、Swaggerは様々なツール群を総称した名称であったため、記法のことを示す名称としてOpen APIに変更されました

現在はver 3.0.3が最新となっているようです

https://www.openapis.org/

記述についてはJSONファイル、もしくはYAML形式で行いますが、今回はYAML形式での紹介をします

(YAMLで書くことの利点はコメントが追加できることです)

準備するもの

Node.js

SwaggerにはEditor, UI, Codegenなどのツールがありますが、今回はそれらを使わずに書く方法を紹介します

はじめ方

YAMLファイルの準備

まずはYAMLファイルを準備します

ここではindex.ymlとしておきましょう

中身はこんな感じです

openapi: 3.0.3
info:
  title: OpenAPI Sample
  description: このAPIはサンプルです
  version: '1.0'
tags:
  - name: Statuses
    description: ステータスエンドポイント
paths:
  /status:
    get:
      tags:
        - Statuses
      description: ステータス取得
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: OK

後ほど順に紹介していきますが、パラメータとしては下記の3つです

info
tags
paths

他にもパラメータはいろいろありますが、個人的に必須と思われるものだけ抜き出しました

ひとまずこれで準備は完了です

HTMLで表示する

本来はSwagger UIでHTMLへと変換して表示しますが、今回はReDocの redoc-cli を使います

Node.jsがインストールされていれば、グローバル環境を汚すことなくnpmパッケージが利用できる、npxコマンドが使えます

npx redoc-cli bundle index.yml

と打つだけで、redoc-static.htmlが出力されます(ファイル名は --output ${output}.html で変更可能です)

ブラウザで開くとこんな感じの画面が表示されると思います

ci等で完成品を出力するのであれば毎回 npx redoc-cli bundleでも問題ないですが、作成中に毎回コマンドを打って再生成するのは面倒ですね...

そこで、redoc-cliにはインタラクティブに表示するコマンドがあります

npx redoc-cli serve ./index.yml

と打つことで、http://127.0.0.1:8080/ でホスティングを行ってくれます

また、最後に --watch をつけることで、保存時に再生成を自動で行ってくれるため、ブラウザの更新だけでドキュメントも更新されます

Open APIの書き方について

前前項で触れたパラメータについて説明します

info

これはドキュメント全体についての説明のための必須項目です

他にも推奨される項目はありますが、基本的には先に書いたものがあれば問題ありません

paths

これが実際にエンドポイントとなる部分です

その配下にGET, POST, PUT, DELETEなどを記述し、実際のパラメータを記載していきます

components

サンプルにはありませんが、componentsというものもあります

これはいくつかのパラメータをまとめたりするもので、ファイル内から参照が可能です

サンプル

例: 書籍のリスト取得とid指定での取得

1ファイルの場合

paths:
  /books:
    get:
      tags:
        - book
      description: 書籍リストを取得する
      responses:
        '200':
          description: 書籍リスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookList'
  /books/{bookId}:
    get:
      tags:
        - book
      description: 書籍を取得する
      parameters:
        - $ref: '#/components/parameters/BookId'
      responses:
        '200':
          description: 書籍
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'

components:
  schemas:
    StatusResponse:
      type: object
      properties:
        result:
          type: string
          example: OK
    BookId:
      type: integer
      example: 1
    Book:
      type: object
      properties:
        id:
           $ref: '#/components/schemas/BookId'
        title:
          type: string
          example: my life
        author:
          type: string
          example: Taro
    BookList:
      type: array
      items:
        $ref: '#/components/schemas/Book'
  parameters:
    BookId:
      name: id
      in: query
      schema:
        $ref: '#/components/schemas/BookId'

components配下には規定のオブジェクトが設定できます

components-object

こうすることで、例えば共通化できそうな部品群をまとめることが可能です

また、redocでは別ファイルで記述したものもHTMLに出力する際に解決してくれるので、ファイルを分けることもできます

複数ファイルの場合

こちらはGitHubレポジトリを作成したので御覧ください

tosaka-n/openapi_sample

また、github-pagesでredocも確認できます

https://tosaka-n.github.io/openapi_sample/

階層構造

├── components
│   ├── parameters
│   │   └── book_id.yml
│   └── schemas
│       ├── book.yml
│       └── book_id.yml
├── paths
│   ├── books.yml
│   └── books_list.yml
├── redoc-static.html
└── index.yml

レポジトリ直下で

npx redoc-cli bundle ./index.yml --output ./docs/index.html

としています

おわりに

以上、ここまでがOpen APIの導入になります

部品が共通化されていると使いやすくなり、メンテナンスにも工数をかけずに行うことができます

また、redocを用いてS3やgithub-pagesにhtmlを配置することで非エンジニアの方でもどこからどういった情報が取れるか、わかりやすくなると思います

現在、僕自身もOpen APIをゴリゴリと書いているので、一緒にがんばりましょう

#openapi #swagger

こちらもどうぞ BearBlogの書き方

↓ よかったら下の[Toast this post]のクリックをおねがいします

なにも起こりませんが、僕が喜びます