ハウテレビジョンブログ

『外資就活ドットコム』『Liiga』『Mond』を開発している株式会社ハウテレビジョンのブログです。

redocly と Prismで始めるOpenAPI

はじめに

外資就活プロダクトチームで主にバックエンドの開発を担当している山本です。

外資就活ドットコムでは、バックエンドに Go で実装された API を使用しています。
API 開発において、正確で一貫性のあるドキュメントは不可欠です。OpenAPI を活用することで、API の設計からドキュメント生成、さらにはモックサーバーの構築までを効率的に行うことができます。

本記事では、@redocly/cli を使ってOpenAPI ドキュメントに対して linter を適用、HTML を生成する方法、そして Prism を用いてモックサーバーを立てる方法を紹介します。

OpenAPI とは何か

OpenAPI は、RESTful API を定義するための標準フォーマットです。 API の構造を yaml またはjson 形式で記述することで、API の設計、開発、運用をスムーズに行うことができます。

環境構築

まず必要なツールをインストールします。

  • Node.js のインストール（必要であれば）
  • @redocly/cli のインストール
npm install @redocly/cli
  • Prism のインストール
npm install @stoplight/prism-cli

※ Docker が必要です。

初期設定

適当なディレクトリを作成し、OpenAPI の yaml ファイルを配置します。

cat index.yaml
openapi: 3.1.0
info:
  license:
    name: "MIT"
    url: "https://example.com"
  version: "1.0.0"
  title: "api doc sample"
  description: |
    About this API
    - You can start the API Mock using this API reference (yaml).
    - It can be accessed at http://localhost:4010.

servers:
  - url: "http://127.0.0.1:4010"
    description: "mock server"
security:
  - googleAuth: []
components:
  securitySchemes:
    googleAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/tokeninfo
          scopes:
            email: Access to your email
            profile: Access to your profile
paths:
  /sample/users:
    get:
      operationId: getUsers
      summary: Retrieve the user list.
      description: |
        Search for users and retrieve the list.
      parameters:
        - in: query
          name: name
          description: user's name
          schema:
            type: string
          required: false
          example: smith
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: smith

OpenAPI ドキュメントの lint（@redocly/cli lint）

lint コマンドの紹介

@redocly/cli の lint コマンドは、OpenAPI ドキュメントの構文エラーやスタイル違反をチェックするツールです。これによりドキュメントの品質を保ちやすくなります。

lint コマンドの実行

npx で実行します。
yaml の記述がルールに従っている場合は、以下のような出力になります。

% npx @redocly/cli lint  index.yaml 
No configurations were provided -- using built in recommended configuration by default.

validating index.yaml...
index.yaml: validated in 11ms

Woohoo! Your API description is valid. 🎉

ここに以下のような POST の記述を追加してみます。

    post:
      operationId: postUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: user's name
                  type: string
                  example: "Joe"

lint コマンドを実行すると

 % npx @redocly/cli lint  index.yaml 
No configurations were provided -- using built in recommended configuration by default.

validating index.yaml...
[1] index.yaml:44:5 at #/paths/~1sample~1users/post/summary

Operation object should contain `summary` field.

42 |       required: false
43 |       example: smith
44 | post:
45 |   operationId: postUser
46 |   description: |

Error was generated by the operation-summary rule.


index.yaml: validated in 15ms

❌ Validation failed with 1 error.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

summary フィールドが無いのでバリデーション違反として検出されます。
このルールは設定ファイルやpluginでカスタムすることが可能です。
Redocly CLI configuration

ドキュメントの生成（@redocly/cli build-docs）

build-docs コマンドは、OpenAPI の yaml ファイルから HTML 形式のドキュメントを生成します。 yaml よりも視覚的に見やすいので、API のリファレンスとして公開する場合はこちらを利用することが多いと思います。

 npx @redocly/cli build-docs index.yaml --output openapi.html

生成されたHTMLは以下のようになります。

openapi.html

モックサーバーの構築（Prism mock）

最後に先ほど作成した yaml ファイルを利用してモックサーバーを起動したいと思います。

Prism の紹介

Prism は、OpenAPI 仕様に基づいたモックサーバーを立てるツールです。
以下のコマンドで起動できます。

docker run --rm -it -p 4010:4010 -v $PWD:/tmp stoplight/prism:4 mock -h 0.0.0.0 /tmp/index.yml

Postman からこのモックサーバーにアクセスすると、OpenAPI の responses に定義された内容が返却されます。

postman

まとめ

  1. 仕様の一貫性と可読性の向上
    OpenAPI を用いて API 仕様をドキュメント化することで、開発チーム全体が共通の理解を持つことができます。API のエンドポイントやリクエスト・レスポンスの形式などが明確に定義されるため、開発者間でのコミュニケーションが円滑になります。これにより、仕様の一貫性が向上し、コードの可読性も高まります。

  2. フロントエンドとバックエンドの並行開発
    OpenAPI ドキュメントを作成し、それを共有することで、フロントエンドとバックエンドの開発作業を非同期的に進めることが可能になります。フロントエンドの開発者は、バックエンドでAPIが実装されるのを待たずに、モックサーバーを利用して API の動作をシミュレートすることができます。これにより、フロントエンドとバックエンドの間での依存関係が減り、開発作業の進行がスムーズになります。

  3. テストの効率化
    OpenAPI ドキュメントを共有することで、テストの効率化も図ることができます。 テスト担当者や QA チームは、OpenAPI 仕様に基づいてテストケースを作成し、API の動作を検証することができます。 また、モックサーバーを利用することで、API が実際の環境にデプロイされる前に、各種テストを検証することができます。

  4. ドキュメントの自動生成と保守性の向上
    OpenAPI 仕様は機械可読性が高く、自動化ツールとの統合が容易です。そのため、OpenAPI ドキュメントを更新する際も、手作業で修正する必要がありません。API の仕様が変更された場合、OpenAPI ドキュメントを更新し、自動生成されたドキュメントを開発チームに提供するだけで済みます。これにより、ドキュメントの保守性が向上し、情報の齟齬が生じるリスクが軽減されます。