はじめに

この記事はOPENLOGI Advent Calendar 20227日目の記事です！

私事ですが2022/12月にオープンロジにジョインしました！頑張ります！
まだ入社して間もないので業務にあまり関われてないのですが個人的に最近やったことを紹介させていただきます！

開発にコミットするAPIドキュメントを作る

皆さんの現場ではAPIドキュメントは開発にコミットしていますか？
開発にコミットしていないAPIドキュメントの例として、

Swaggerを誰かが作ったけどメンテナンスされていない
メンテナンスしているけど誰も見ていない
メンテナンスしているけど信頼性が担保されていないので使えない

みたいな状態になっていませんか？

APIドキュメントを書くと何がいいの？

APIドキュメントって何に使うの？と思うエンジニアも意外と多いのではないでしょうか
実際SwaggerやStoplightで生成したopenapi.ymlが開発にコミットして開発の効率やクオリティを上げる事例を紹介します

APIテストの自動化

Dreddというツールを使ってopenapiのテストを行うことができます。
PHPUnitなどのテストコードを書かずに、openapiで記述されたレスポンスの型が帰ってくるかをテストできます。

Dredd
https://github.com/apiaryio/dredd
事例
https://qiita.com/EightT/items/c0ad00520c011f2d8361

モックサーバーの生成

openapiで記述した内容を簡単にモックサーバーにしてくれます
本記事では事例としてPrismでモックサーバーを作ってみましょう！

Prismを使ったモックサーバーの生成

モックサーバーを生成するために適当なopenapi.ymlを作ります。

openapi.yml

openapi: 3.1.0
info:
  title: openapi
  version: '1.0'
  summary: sample openapi project
servers:
  - url: 'http://localhost:3000'
paths:
  '/users/{user_id}':
    parameters:
      - schema:
          type: string
        name: user_id
        in: path
        required: true
    get:
      summary: get user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
                  post_count:
                    type: integer
      operationId: get-users-user_id

dockerでprismサーバーを作ってみます

docker-compose.yml

version: "3"
services:
  mock:
    image: stoplight/prism:3
    container_name: "mock-api"
    ports:
      - "14010:4010"
    command: mock -h 0.0.0.0 /openapi.yaml
    volumes:
      - ./openapi.yaml:/openapi.yaml

そしたら、

$ docker-compose up

あとは、モックサーバーにリクエストを投げてみると、期待するものと同じ型のレスポンスが返ってきます。

リクエスト：

http://localhost:14010/users/aaaaaa

レスポンス：

{"name":"string","description":"string","post_count":0}

良さそうですね、

終わりに

openapiの整備でクライアント側の型自動生成など他にもできることがあるのですが、入社してすぐアドベントカレンダー書くことになったので時間が足りませんでした。また別の機会に！

openapi.ymlで開発を効率化しよう！