OpenAPIの基礎

OpenAPIとは

OpenAPIは、REST APIの仕様を 機械も人も読める形 で記述するためのフォーマット。

たとえば、次のような情報を1つの仕様として表現できる。

• どんなエンドポイントがあるか
• HTTPメソッドは何か
• リクエストBodyはどんな形か
• レスポンスはどんな形か
• どんなステータスコードが返るか
• 認証方式は何か

要するに、

OpenAPI = APIの仕様書を共通フォーマットで書くためのルール

と考えるとよい。

なぜ必要か

API開発では、バックエンド・フロントエンド・QA・外部連携先など、複数の人が同じAPI仕様を見る。

仕様が口頭やREADMEだけだと、次のようなズレが起きやすい。

• フロントが送るBodyとバックエンドが期待するBodyが違う
• どのステータスコードが返るのか分からない
• 認証が必要なAPIかどうか分からない
• API変更時にどこが変わったのか追いにくい

OpenAPIで仕様を表現しておくと、APIの形を共通認識にしやすくなる。

OpenAPIに書かれる内容の例

たとえば POST /users なら、OpenAPIには次のような情報が入る。

paths:
  /users:
    post:
      summary: ユーザーを作成する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: taro@example.com
                name:
                  type: string
                  example: Taro
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request

実際に手で全部書くこともできるが、NestJSでは @nestjs/swagger を使ってControllerやDTOから生成することが多い。

Swagger UIとの違い

ここが混同しやすい。

• OpenAPI … API仕様のフォーマット
• Swagger UI … OpenAPI仕様をブラウザで見たり試したりするための画面

関係としては次のイメージ。

Controller / DTO
↓
OpenAPI仕様
↓
Swagger UIで表示

OpenAPIは仕様そのもの。Swagger UIはそれを見やすく表示するツール。

NestJSではどう使うか

NestJSでは @nestjs/swagger を使うと、ControllerやDTOに付けたデコレータからOpenAPI仕様を生成できる。

たとえばDTOに次のように書く。

@ApiProperty({ example: "taro@example.com" })
email!: string;

すると、Swagger UI上で email の例や型が表示される。

Controllerに次のように書く。

@ApiTags("users")
@Controller("users")
export class UsersController {}

すると、Swagger UI上で users グループとして整理される。

実務で何に使うか

• フロントエンドとのAPI仕様共有
• QAがAPIを手元で試す
• APIレビュー
• 外部連携先への仕様共有
• クライアントコード生成
• API変更差分の確認

小さなAPIでも、Swagger UIで見える形にしておくと「今どんなAPIがあるか」を把握しやすい。

次に読む

NestJS + Swaggerでは、NestJSのController / DTOからOpenAPI仕様を生成し、Swagger UIで確認できるようにする。

参考

• OpenAPI Specification
• NestJS OpenAPI