OpenAPIをはじめて触ってみる - はなちるのマイノート

はじめに

今回はOpenAPIについて取り上げたいと思います。

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

// DeepL翻訳
OpenAPI仕様（OAS）は、HTTP APIのための標準的でプログラミング言語に依存しないインターフェース記述を定義しています。これにより、ソースコードへのアクセス、追加のドキュメント、ネットワークトラフィックの検査などを必要とせずに、人間とコンピュータの両方がサービスの機能を発見し理解することができます。

GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository

また備忘録的な記事なので、ちゃんとOpenAPIへの理解を深めたい方は公式ドキュメントを見てみてください。
github.com

はじめに
動作の確認方法
基礎的な書き方
参考

動作の確認方法

オンラインで動作確認できるSwagger Editorというサイトがあるみたいです。

editor.swagger.io

ただ今回は手元で試したいので、VS Codeの拡張ツールであるSwagger Viewerを利用したいと思います。
https://github.com/arjun-g/vs-swagger-viewer

実際に動作するのか試してみましょう。

適当にsample.yamlというファイルを生成し、以下のコードを記述します。

openapi: 3.0.2
info:
  title: "Sample API"
  description: "Sample API"
  version: "1.0.0"
servers:
- url: /
- url: http://localhost:3000
  description: "Local machine"
paths:
  /users/{userId}:
    get:
      summary: 指定されたidのユーザーを取得します
      parameters:
      - name: userId
        in: path
        description: 取得したいユーザーのID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: 成功時のレスポンス
          content:
            '*/*':
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int32
                  name:
                    type: string
                    example: ユーザー名
components: {}

あとはVS Codeでsample.yamlを右クリック、Preview Swaggerを押せば以下の画面が立ち上がります。

また右クリック以外にも以下の方法があります。

To start

Open the swagger file and press F1.
Run the Command Preview Swagger.

OR

Press Shift + Alt + P

OR

Right click file in explorer panel and click Preview Swagger

基礎的な書き方

OpenAPIはjsonかyaml形式で記述し、大文字と小文字を区別します。

またルートに配置されるOpenAPIドキュメントはopenapi.jsonかopenapi.yamlという名前が推奨されるとのこと。

構造の概要

必要最低限であれば以下のように記述します。

openapi: "3.0.3"
 
info:
  title: "..."
  version: "..."

paths:
  ...

Field Name	Type	Description
openapi	string	REQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
info	Info Object	REQUIRED. Provides metadata about the API. The metadata MAY be used by tooling as required.
paths	Paths Object	REQUIRED. The available paths and operations for the API.

OpenAPI-Specification/3.0.3.md at main · OAI/OpenAPI-Specification · GitHub

上記URLにてそれ以外のField Nameに関する情報もありますので気になる方はチェックしてみてください。

servers
components
security
tags
externalDocs

info Object

InfoではAPIに関するメタデータを記述します。

The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

Field Name	Type	Description
title	string	REQUIRED. The title of the API.
description	string	A short description of the API. CommonMark syntax MAY be used for rich text representation.
termsOfService	string	A URL to the Terms of Service for the API. MUST be in the format of a URL.
contact	Contact Object	The contact information for the exposed API.
license	License Object	The license information for the exposed API.
version	string	REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

OpenAPI-Specification/3.0.3.md at main · OAI/OpenAPI-Specification · GitHub

必要最低限なサンプルは以下の通り。

info:
  title: "Sample App"
  version: "1.0.0"

paths Object

pathsには個々のエンドポイントおよびその操作への相対パスを記述します。

Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to ACL constraints.

pathsを加えたシンプルなsample.yamlファイル。

openapi: "3.0.3"
 
info:
  title: "Sample App"
  version: "1.0.0"

paths:
  "/sample/{sampleId}":
    get:
      parameters:
      - name: "sampleId"
        in: "path"
        required: true
        schema: { type: string }
      responses:
        200:
          description: "Success response"