🛜

初めてOpenAPIを触ったお話

2025/01/31に公開
2

こんにちは。ねこがくれです。
今日はOpenAPIというフレームワークを初めて触った時の感想や改善点などまとめていこうと思います。

そもそもOpenAPIってなんぞや

私も先週までその存在を知りませんでした。
ココによると

OpenAPIは、REST API の API 記述形式です。OpenAPI ファイルを使用すると、次の内容を含む API 全体を記述できます。
利用可能なエンドポイント(/users)と各エンドポイントでの操作(GET /users、POST /users)
操作パラメータ 各操作の入力と出力
認証方法

  • 連絡先情報
  • ライセンス、
  • 利用規約、
  • その他の情報。
    API 仕様は YAML または JSON で記述できます。この形式は学習しやすく、人間と機械の両方にとって読みやすいものです。完全な OpenAPI 仕様は GitHub で確認できます: OpenAPI 3.0 仕様

ということらしいです。
はて?REST APIってなんだ?って私は思いました。まずはそこからです。

REST APIとは

私はこの記事を参考にして勉強しました。
つまるところ、

GET https://api.scratch.mit.edu/users/sei6sei/

とかのGETの部分のことです。
正直OpenAPIでめちゃくちゃ簡単なAPI規格だけ作るとかなら細かく勉強しなくていいと思いました。
エンジニアとか開発者の人でPOSTメソッドやGETメソッドを使ったことがない人はあまりいないと思うので大体わかってる方が多いと思います。

OpenAPIで何を作った?

私がOpenAPIを勉強したのには、私が所属している団体が運営しているSNSが現在APIベースで動いておらず、直接DBに書き込んでいます。
なので、APIを使った仕様に一気に刷新しよう!スマホアプリ化も難しいし!ということになったのでAPIを作ることになりました。
そして、細かい詳細は偉大なるChatGPT君にアイデアを出してもらい、yaml形式に落とし込んだのがこれです。
一部抜粋すると、

openapi: 3.0.0
info:
  title: TalkNeT API
  version: 1.0.0
  description: TalkNeTのAPI

paths:
  /posts:
    post:
      summary: newPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                content:
                  type: string
              required:
                - sessionId
                - content
      responses:
        '201':
          description: Post success
          content:
            application/json:
              schema:
                type: object
                properties:
                  postId:
                    type: string
        '401':
          description: Auth failed

こういう感じです。
これを書いているときに一度地獄を見ました。

私は基本、VScodeで作業しているのですが、とくに

        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                content:
                  type: string
              required:
                - sessionId
                - content

の部分で挫折しました。
なぜなら、(今となっては馬鹿でしかないですが)このサイトを使っていなかったからです。

それまではいろんなサイトを参考にしながら、あってる!?あってる!?この書き方でいいのかこれ!? と、頭でひたすら実行(というよりかはビジュアル化)させながら書いてたのでここで二時間ぐらい空費してしまいました...。

これはおかしいと思い色々調べてやっと、このサイトの存在を知ったわけです。

最後に

OpenAPIは全体的にとても使いやすく定義もしやすいので今後も重宝しそうです...。
これからOpenAPIさわるよ~という方は「絶対に」このサイト、もしくはVScodeの拡張機能を使いましょう。本当に地獄を見ます。

最後まで読んでくださってありがとうございます。では。

Discussion

YuneKichiYuneKichi

VSCode ExtensionでOpenAPI (Swagger) Editorというものがあります。
デフォルトでSwagger UIによるプレビューが使えるので、Swagger Editorと同程度のエラーチェックはできるかと。
他にRedocによるプレビューもできます。

なお、必須ではないものの、

をしておくと、自動生成コードが使いやすくなります。
Swagger EditorのメニューにもGenerate ServerGenerate Clientがありますが、他にもOpenAPI Generatorや言語ごとに特化したコード生成ツールがあります。

上記の適用例

※OpenAPI 3.0系最新の3.0.4だとSwaggerがエラーを吐くので3.0.3にしています。

openapi: 3.0.3
info:
  title: TalkNeT API
  version: 1.0.0
  description: TalkNeTのAPI

paths:
  /posts:
    post:
      summary: newPost
      operationId: createPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCreate"
      responses:
        '201':
          description: Post success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        '401':
          description: Auth failed

components:
  schemas:
    PostCreate:
      type: object
      properties:
        sessionId:
          type: string
        content:
          type: string
      required:
        - sessionId
        - content
    Post:
      type: object
      properties:
        postId:
          type: string