OpenAPIの書き方｜YAMLのテンプレートとチームで使う運用

OpenAPIとは、REST APIの仕様（URL、パラメーター、リクエスト、レスポンス、認証など）を、YAMLやJSONで記述するための標準の形式です。以前は「Swagger」と呼ばれていました。OpenAPIで仕様書を書いておくと、見やすいドキュメントの自動生成、クライアントやサーバーのコードの生成、仕様どおりかのテストまで、さまざまなツールで活用できます。

この記事では、注文APIを例に、そのまま使えるYAMLのテンプレートで書き方を解説します。テンプレートは、OpenAPIのリンター（Redocly CLI）で検査し、エラーがないことを確認しています。後半では、リントやドキュメントの生成を含めた、チームで仕様書を使い続けるための運用も紹介します。

OpenAPIの構造の早見表

テンプレート：注文API

注文の作成と取得を行うAPIの定義です。Redocly CLIでの検査結果は「valid（エラーなし）」でした。

openapi: 3.1.1
info:
  title: 注文API
  version: 1.0.0
  description: 注文の作成・取得を行うAPIです。
servers:
  - url: https://api.example.com/v1
    description: 本番環境
security:
  - bearerAuth: []
tags:
  - name: orders
    description: 注文
paths:
  /orders:
    post:
      tags: [orders]
      operationId: createOrder
      summary: 注文を作成する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
            example:
              item: マウス
              quantity: 2
      responses:
        '201':
          description: 作成された注文
          headers:
            Location:
              description: 作成された注文のURL
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /orders/{orderId}:
    get:
      tags: [orders]
      operationId: getOrder
      summary: 注文を1件取得する
      parameters:
        - name: orderId
          in: path
          required: true
          description: 注文ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: 注文
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    OrderStatus:
      type: string
      enum: [pending, paid, shipped, cancelled]
    Order:
      type: object
      required: [id, item, quantity, status]
      properties:
        id:
          type: integer
          format: int64
          example: 123
        item:
          type: string
          example: マウス
        quantity:
          type: integer
          minimum: 1
          example: 2
        status:
          $ref: '#/components/schemas/OrderStatus'
    OrderCreate:
      type: object
      required: [item, quantity]
      properties:
        item:
          type: string
          minLength: 1
          maxLength: 100
        quantity:
          type: integer
          minimum: 1
          maximum: 99
    Problem:
      type: object
      description: RFC 9457 のエラー形式
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
  responses:
    Unauthorized:
      description: 認証されていません
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: リソースが存在しません
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationError:
      description: 入力内容に誤りがあります
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

書き方のポイント

paths：URLとメソッドごとに書く

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: 注文を1件取得する

parameters：どこに値を入れるか

schemas：データの形と制約

制約（必須・範囲・形式）まで書いておくと、仕様書を見ただけで入力チェックのルールがわかり、仕様書からバリデーションのコードやテストを作ることもできます。

components と $ref：同じものを2回書かない

注文のデータ（Order）や、エラーのレスポンス（NotFound）は、複数のエンドポイントで使います。components に1回だけ定義し、$ref で参照します。

responses:
  '404':
    $ref: '#/components/responses/NotFound'

同じ定義をコピーすると、片方だけ直して食い違う原因になります。2回以上使うものは、components にまとめます。

認証：securitySchemes

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

ルートの security はAPI全体に適用されます。ログインのように認証が不要なエンドポイントでは、そのエンドポイントに security: [] と書いて外します。

エラーの形式を揃える：RFC 9457

テンプレートでは、エラーのレスポンスを application/problem+json（RFC 9457の形式）で定義しています。すべてのエラーを同じ Problem スキーマで返すと決めておくと、画面側で共通のエラー処理が書けます。

リントで間違いを見つける

OpenAPIのファイルは長くなりやすく、手で書くと間違いが混ざります。リンターを使うと、機械的に見つけられます。

npx @redocly/cli lint openapi.yaml

テンプレートに、わざと2つの間違いを入れて検査した結果です。

Can't resolve $ref
Every operation must have a unique `operationId`.
❌ Validation failed with 2 errors and 3 warnings.

リンターには、プロジェクト独自のルール（「すべてのエンドポイントに説明を書く」「URLは複数形の名詞にする」など）を追加することもできます。CIで毎回実行すると、仕様書の品質を保てます。

ドキュメントとして表示する

npx @redocly/cli build-docs openapi.yaml -o docs.html

実際に、この形式の仕様書から、1ファイルのHTMLドキュメントが生成できることを確認しました。

コードを生成する

設計を先に書くか、コードから作るか

画面の開発者とAPIの開発者が別々の場合は、設計ファーストがおすすめです。仕様書が決まれば、モックサーバーを立てて、APIの完成を待たずに画面の開発を始められます。

チームで使い続けるための運用

OpenAPIのバージョンの違い

新しく書くなら、多くのツールが対応している3.1がおすすめです。3.0から3.1に移るときは、nullable: true の書き方などが変わる点に注意します。

よくある質問

Q. SwaggerとOpenAPIの違いは何ですか？ A. 仕様の名前は、Swagger 2.0の後に「OpenAPI」に変わりました。現在「Swagger」は、Swagger UIやSwagger Editorなどのツールの名前として使われています。

Q. YAMLとJSONのどちらで書けばいいですか？ A. どちらでも同じ内容を表せます。人が書いて読むならYAMLの方が短く、読みやすいため、よく使われています。

Q. AIに仕様書を書かせてもいいですか？ A. 下書きを作るのに向いています。ただし、リンターで検査し、業務のルール（必須の項目、値の範囲）が正しいかは人がレビューします。

まとめ

• OpenAPIは、REST APIの仕様をYAMLやJSONで書く標準の形式
• 基本は paths（エンドポイント） と components（使い回す部品）、$ref で参照する
• 制約（必須・範囲・形式）と例まで書くと、仕様書だけで入力のルールがわかる
• 認証は securitySchemes、エラーは RFC 9457の形式に揃える
• リンターをCIで実行し、仕様書の間違いをマージ前に見つける
• 画面とAPIを並行して作るなら、設計ファーストがおすすめ

株式会社RJCでは、チームで気持ちよく開発するための設計の工夫を、プロジェクトの中で仲間と磨いています。こうした知識を共有しながら、日々学び合っています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。