【備忘】（今更ながら）OpenAPIとは

OpenAPIとは

Open APIとは、APIの仕様を記述するためのフレームワークやツールの一つ。

APIはソフトウェアアプリケーション同士が情報をやり取りするためのインターフェースであり、OpenAPIはそのAPIの仕様書を標準化し、簡単に作成・理解できる形式で提供している。

また、OpenAPI＝「Open API Spesification」の略で、REST APIの記述フォーマットを指している。
※REST APIとは、Webアプリケーション同士の情報のやり取りを安全に行うための規格のこと。

つまりOpenAPIは、安全な通信のために「どのような項目をどのような形式で記載すればよいのか」という仕様を定義している

What Is OpenAPI?

特徴

1.オープンな規格

OpenAPIはオープンな規格であり、誰でも利用することが可能。
これにより、APIの利用や開発が容易になり、イノベーションを促進できる。

2.RESTfulな設計

OpenAPIはRESTfulな設計に基づいている。
これにより、シンプルで使いやすいAPIを提供することができ、開発者が迅速にアプリケーションを構築可能。

3.ドキュメントの豊富さ

OpenAPIは豊富なドキュメントが提供されており、開発者がAPIの利用方法や仕様を簡単に理解できる。
これにより、開発プロセスがスムーズに進行可能となる。

OpenAPIでできること

大きく分けて3点ある

1.OpenAPIドキュメントの自動生成

OpenAPIを利用すると、記載内容や記述形式が統一されたドキュメントを自動生成可能。
API仕様書の作成者によって内容に相違出ることがなくなるため、開発者同士で仕様のやり取りをスムーズに実施可能。

2.モックサーバーの構築

OpenAPIではテストで使用するモックサーバーの構築が可能。
※モックサーバーとは、Webサーバーがすぐに用意できないときに、ブラウザ側でテスト的に使用するための簡易サーバーのこと。
（モックには「見せかけの」「試作品」などの意味がある）
モックサーバーはプログラムの動作をすぐ確認したいときに便利で、開発やテストをスムーズに実施可能。

3.テストの実行

OpenAPIで生成したドキュメントをもとに、テストを実行することが可能。
テストケースが大量に自動生成されるため、開発者が気付かなかったバグを発見することができ、機能・負荷・セキュリティなど、Webアプリケーションが相互通信するために満たすべき基準を確認するのに役立つ。

メリット・デメリット

メリット

API仕様書のフォーマットを統一できる

API仕様書の作成者が変わっても、記述項目などのフォーマットを統一可能。

API仕様書の記述が楽になる

ドキュメントの自動生成ができるツールを導入すれば、API仕様書の記述が非常に楽になる。

バージョン管理が楽になる

更新履歴が把握できるため、Excel等で作成したAPI仕様書に比べてバージョン管理が楽になる。

コーディング・テストを効率化できる

ツールを使用することでコードやテストケースが自動生成されるため、人の手で作成するよりも効率的になる。

デメリット

OpenAPIを使いこなすためにある程度学習が必要

OpenAPIの機能を活用するには、さまざまなツールの導入が必要となる。
ツールの使い方を覚えるために、ある程度の学習が求められる可能性あり。

最新のOpenAPIに非対応のツールがある

ツールがバージョンアップされず、最新のOpenAPIに対応していないことがあり。

その他

OpenAPIの記載方法

「YAML形式」と「JSON形式」の2種類あり

記載方法

具体的な記載方法などは、下記ドキュメントに記載あり
OpenAPI-Specification/versions/3.0.3.md

ChatGPTにYAML形式とJSON形式の記載例を聞いてみた。

YAML形式

swagger: '2.0'
info:
  title: Sample Pet Store API
  description: This is a sample API for managing pets in a pet store.
  version: 1.0.0
basePath: /api
schemes:
  - https
paths:
  /pets:
    get:
      summary: Get a list of all pets
      description: Returns a list of all pets available in the store.
      responses:
        200:
          description: A list of pets
          schema:
            type: array
            items:
              $ref: '#/definitions/Pet'
    post:
      summary: Add a new pet
      description: Adds a new pet to the store.
      parameters:
        - name: pet
          in: body
          description: Pet object to be added to the store
          required: true
          schema:
            $ref: '#/definitions/Pet'
      responses:
        201:
          description: Successfully added the pet
          schema:
            $ref: '#/definitions/Pet'
definitions:
  Pet:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: The ID of the pet
      name:
        type: string
        description: The name of the pet
      breed:
        type: string
        description: The breed of the pet
    required:
      - name

JSON形式

{
  "swagger": "2.0",
  "info": {
    "title": "Sample Pet Store API",
    "description": "This is a sample API for managing pets in a pet store.",
    "version": "1.0.0"
  },
  "basePath": "/api",
  "schemes": [
    "https"
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "Get a list of all pets",
        "description": "Returns a list of all pets available in the store.",
        "responses": {
          "200": {
            "description": "A list of pets",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Pet"
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add a new pet",
        "description": "Adds a new pet to the store.",
        "parameters": [
          {
            "name": "pet",
            "in": "body",
            "description": "Pet object to be added to the store",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Pet"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Successfully added the pet",
            "schema": {
              "$ref": "#/definitions/Pet"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Pet": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "The ID of the pet"
        },
        "name": {
          "type": "string",
          "description": "The name of the pet"
        },
        "breed": {
          "type": "string",
          "description": "The breed of the pet"
        }
      },
      "required": [
        "name"
      ]
    }
  }
}

私的まとめ

OpenAPIは、APIの設計・ドキュメンテーションおよび利用を容易にするオープンな規格であり、どのような項目をどのような形式で記載すればよいのかという仕様を定義しているものである。