開発環境

• PhpStorm
• GitHub Copilot
• 自社フレームワーク

ルールをきめるの巻

我が株式会社クレアヴォイアンスではAPI仕様をMarkdown記法で記述して管理しているのですが仕様変更の際に更新を忘れがち。
その上フォーマットが決まっておらず人の書いたやつは読んでもよくわかんない。
更にドキュメントの場所がアチコチ散らばっており、まあ結局ソースを見直すハメになるのです。

OpenAPI書式導入するの巻

とりあえず書式だけでも共通化する。

swagger-phpというのでOpenAPI書式で自動生成してくれるらしいのですが自社フレームワークのディレクトリ構成だとうまくいかない様なのでCopilotにControllerを読ませてopenapi.ymlを書かせる。

それでできたのがこれ

openapi: 3.0.3

info:
  title: User Data API
  version: 1.0.0
  description: ユーザデータの処理API

servers:
  - url: http://127.0.0.1:8080

paths:
  /api/userdata/:
    post:
      summary: ユーザ情報の取得

      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserDataRequest"
            examples:
              basicRequest:
                value:
                  identifier: clairvoyance
      responses:
        "200":
          description: ユーザ情報取得成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDataResponse"

components:
  schemas:

    UserDataResponse:
      type: object
      properties:
        identifier:
          type: string
          example: "clairvoyance"
        username:
          type: string
          example: "Clairvoyance"
        tel:
          type: string
          example: "050-3647-4548"
        address:
          type: string
          example: "〒150-0031 東京都渋谷区桜丘町23-17"

    UserDataRequest:
      type: object
      required:
        - identifier
      properties:
        identifier:
          type: string
          description: ユーザID
          example: clairvoyance

読めるようにする

API仕様は主に開発スタッフ向けの情報であるため、専用の公開サイト等は用意せず、リポジトリで管理している openapi.yml を PHPStorm のプラグイン経由で参照することとした

PHPStormで

Settings>Plugin>OpenAPI Specifications

インストールするとこんな感じでよめる！

なんとTry itすると実行もできる！
これでちゃんと仕様と仕様書が正しい関係でいられるね！ありがとう☺