MENU

OpenAPI

OpenAPIは、RESTful APIを記述するための仕様で、APIの設計、開発、運用を簡素化し、標準化するためのツールです。以前はSwaggerとして知られていましたが、OpenAPI Initiative（OAI）によって管理されるようになり、現在ではOpenAPI Specification（OAS）として広く知られています。

OpenAPIの特徴と利点

  1. APIの標準化:
    OpenAPI Specificationは、APIのエンドポイント、リクエストパラメータ、レスポンスフォーマット、認証方法などを標準化された形式で記述します。これにより、異なる開発者やチーム間でのAPIの理解と利用が容易になります。
  2. 自己ドキュメント化:
    OpenAPIドキュメントを作成すると、それ自体がAPIの詳細なドキュメントとなります。これにより、APIの使用方法やエンドポイントの詳細を容易に参照できるようになります。
  3. 自動生成ツールとの連携:
    OpenAPI Specificationは、コード生成ツールやドキュメント生成ツールと連携することができます。例えば、Swagger UIを使用して視覚的なAPIドキュメントを生成したり、Swagger Codegenを使用してクライアントやサーバーのコードを自動生成したりすることができます。
  4. 相互運用性:
    OpenAPIは広く採用されており、多くのプログラミング言語やフレームワークでサポートされています。これにより、異なる技術スタック間でのAPIの利用が容易になります。

OpenAPIドキュメントの構造

OpenAPIドキュメントはYAMLまたはJSON形式で記述され、以下の主要な要素を含みます。

  1. 基本情報:
    APIのバージョンやタイトル、説明などのメタデータを含みます。
   openapi: 3.0.0
   info:
     title: Sample API
     description: API for demonstrating OpenAPI
     version: 1.0.0
  1. サーバー情報:
    APIがホストされるURLを指定します。
   servers:
     - url: https://api.example.com/v1
  1. パス（エンドポイント）:
    APIのエンドポイントと、それに対するHTTPメソッド、リクエスト、レスポンスを定義します。
   paths:
     /users:
       get:
         summary: Get a list of users
         responses:
           '200':
             description: A JSON array of user names
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     type: string
  1. コンポーネント:
    再利用可能なデータモデルやスキーマを定義します。
   components:
     schemas:
       User:
         type: object
         properties:
           id:
             type: integer
             format: int64
           name:
             type: string
  1. セキュリティ:
    APIの認証と認可の方法を定義します。
   security:
     - apiKeyAuth: []
   components:
     securitySchemes:
       apiKeyAuth:
         type: apiKey
         in: header
         name: X-API-Key

OpenAPIの使用例

Swagger UIを使用したドキュメント生成

Swagger UIは、OpenAPIドキュメントを視覚的に表示するためのツールです。APIのエンドポイントを試すこともできます。

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.30.0/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.30.0/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      const ui = SwaggerUIBundle({
        url: "https://path/to/your/openapi.yaml",
        dom_id: '#swagger-ui',
      });
    }
  </script>
</body>
</html>

Swagger Codegenを使用したコード生成

Swagger Codegenを使用すると、OpenAPIドキュメントからクライアントやサーバーのコードを自動生成できます。

swagger-codegen generate -i path/to/openapi.yaml -l java -o /path/to/output

OpenAPIは、APIの設計と管理を効率化し、開発者が高品質なAPIを提供するのに役立つ強力なツールです。

用語集