OpenAPIとは？
API開発やAPIセキュリティへの関心は飛躍的に高まっており、ウェブAPI、モバイルAPIともに著しい成長を遂げている。
API開発について語る際、OpenAPIは必ず言及される技術である。この一つの技術により、APIの仕組みの理解がこれまで以上に容易になった。API開発やセキュリティに携わる専門家は、サーバ設計、コード生成、テスト実施などにおいて、この標準仕様を活用している。
OpenAPIはAPI経済の発展と活用において重要な役割を果たしている。API経済やAPI開発に関わるなら、OpenAPIの知識は欠かせない。本稿はOpenAPIについて解説する。
OpenAPIの概要
Tony Tamが生み出したOpenAPIは、HTTP APIを説明し定義するための国際的に認められた手法です。もともとは Swagger として誕生し、2015年にSmartbearによってOpen Initiativeへ寄贈されました。Linux FoundationやAmazonなど、IT業界の大手がこの取り組みを支援しています。
このような強力な支援を背景に、OpenAPIはAPI開発とセキュリティの分野で信頼される存在です。多様なプロトコルやインターフェイス、エコシステムに対応するための課題を解消し、データ管理を一本化して効率性を向上させます。
OpenAPIはどのように使われ、なぜ利用されるのか？
OpenAPIの基本的な定義が明らかになったところで、OpenAPIを使って実現できることを紹介する。
- OpenAPIはAPIの共通言語として機能し、主要な仕様作成からセキュリティ設計までを網羅する。また、アプリ開発用のスタブコード生成によく利用される。
- APIスキーマの唯一の情報源となり、統一されたAPIスタイルと運用方針の策定を容易にする。
- 統一された情報源を利用することで、APIエンジニアや開発者はSDK、コードライブラリ、ドキュメントなど、重要なAPI資料を自動生成できる。
- OpenAPIは、その機能を最大限に発揮すれば、APIの妥当性検証、セキュリティチェック、コード解析も実施可能である。
- 最終的なアプリのインターフェイスを期待通り、またはクライアントの要望に近づけるため、エンジニアはモックサーバを生成し、同時にインターフェイスの試作品を検証できる。
- 開発段階でAPIリクエストのテストやセキュリティ脅威の検出が可能である。
上記のように、OpenAPIは多岐にわたる用途で利用される。しかし、なぜAPI開発者やセキュリティ専門家はOpenAPIに大きな信頼を寄せるのか？
ここから主要な理由を解説する。
エラーを防ぎ、大幅に時間を節約
API開発で最も骨の折れる作業はコーディングです。時間がかかり、開発者は興味を失いがちですが、コーディング作業から逃れることはできません。
アプリ開発を行うなら、この段階を乗り越える必要があります。OpenAPIの導入により、定義をコードに自動変換できる有名な自動化ツールが提供され、煩雑なコーディング作業に煩わされずにアプリ開発が実現できます。
コード作成が自動化され、機械支援されるため、人為的なミスも大幅に減少します。
堅牢なAPIセキュリティ
コーディングの手間から開発者がだらけると、バグが入り込みやすくなります。アプリ完成前に多くのバグが混入すると、後での対処は非常に困難となり、大きなセキュリティリスクとなります。
このような場合、早期の対策が肝要です。
OpenAPIは、統一された言語を用いることでソースコードからAPI詳細を抽出する必要がなくなり、生成時からコードの挙動を監視することで、初期段階で潜在的なセキュリティ脅威を把握できます。さらに、OpenAPIで生成されたAPIは扱いやすい。
セキュリティの隙間やリスクは隠されたままではなく、容易に発見できる。
円滑なコミュニケーション
話し手と聞き手が異なる言語を使用すれば、内容の理解は非常に困難となる。
API開発においても、コードと処理が異なる言語で記述される場合、同様の問題が生じる。
OpenAPIは標準フォーマットであるため、外部のユーザーとの情報共有が円滑になり、必要な情報が明確に伝わる。RESTful APIの基本を押さえていれば十分である。
OpenAPIでは、YAMLまたはJSONがAPI仕様として広く使われ、どちらも理解しやすく、人間も機械も読み取りやすいため、情報伝達に煩わされることはない。
OpenAPIの例（コードスニペット）
JSONまたはYAMLを使ってリクエストを作成できます。以下に例を示す。
GETリクエスト
GETリクエストは、データベースからデータ（またはレコード）を取得する。
get:
summary: employee
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
employee_name:
type: string
employee_role:
type: string
operationId: get-employees-employee_id
description: Fetch employee’s role/designation by employee’s name
POSTリクエスト
POSTリクエストは、新たなパス（異なるエンドポイント）を作成してデータベースに新規レコードを追加するために使用される。以下にその例を示す。
post:
summary: employees
operationId: post-employees
responses:
'201':
description: Created
description: Append a new Employee record to company’s Database
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: stringPUTリクエスト
PUTリクエストは、レコードの詳細を編集するために使用される。まずGETリクエストで更新対象のレコードを取得する必要がある。以下に例を示す。
get:
# Operation’s GET details go hereput:
summary: employee update
operationId: put-employees-employee_id
responses:
'204':
description: No Content
description: Edit information for an employee
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: stringOpenAPIオブジェクト
- OpenAPI
これは文書のセマンティックバージョン管理のためのオブジェクトです。OpenAPIは文書のバージョンを示し、バージョン番号は3つの部分から成る。
Major: 大きな追加や変更があった際に増加する。
Minor: 機能の強化や更新時に増加する。
Patch: エラーやバグ修正のためのパッチ適用時に増加する。
Format = Major.Minor.Patch
Examples: 5.2.1, 1.0.0, 8.2.0
Note: MinorおよびPatchは後方互換性を保つ必要がある。
- Info
このオブジェクトは、タイトル、バージョン、連絡先、ライセンス、利用規約、説明などのメタデータを含み、特にタイトルとバージョンは必須である。
- Servers
このオブジェクトでは、URLやパスなどのサーバ情報を指定できる。OpenAPI 3.0以降、ホスト名、ポート、パス、説明（任意）も指定でき、複数サーバの場合は配列で渡せる。
- Components
このオブジェクトは再利用性とAPIの安全性を高め、以下のデータ構造を持つ他のオブジェクトのスキーマを定義できる：
- schema
- securitySchemes
- responses
- parameters
- callback
- examples
- links
- headers
- requestBodies
- Tags
通常、タグは名前、説明、externalDocsフィールドから構成される。externalDocsは任意だが、説明はMarkdown形式で記述でき、後に操作オブジェクトと関連付けることも可能である。
- Paths
このOpenAPIオブジェクトはエンドポイントの詳細を指定し、HTTPメソッドとしてGet、Post、Put、Patch、Trace、Delete、Options、Headのいずれかの操作を定義できる。また、各リクエストのレスポンスも指定できる。
パスを指定する方法は以下の4通りである：
- 波括弧で囲んだURL
- クエリとして
- ヘッダー内で
- クッキーを用いて
- Security
APIのセキュリティ要件を踏まえ、認証方法を示すsecuritySchemesコンポーネントを指定する必要がある。現在、サポートされている方法は以下の通りである：
- ExternalDocs
タグ、スキーマ、操作向けにexternalDocsオブジェクトを作成することで、利用者にとって分かりやすく最新のドキュメントを提供できる。
OpenAPI仕様への入門：誤解を解く
OpenAPIとOpenAPI仕様は多くの点で似た用語だが、その違いは非常に微妙である。違いを理解することは重要だ。
一般に、OpenAPI仕様は実用的で必要に応じた機械可読のインターフェイスファイルを生成するためのオープンソース形式とプロセスであり、REST APIやウェブサービスの生成、説明、利用、可視化に活用される。
誕生当初はSwagger仕様として知られていたが、Smartbearが採用した後、現在の名称となった。
これにより、開発者は入力パラメータ、出力、主要な認証方法、APIの安全対策、エンドポイントおよび操作の詳細など、APIの重要項目を明示できるようになった。
OpenAPIの利点
これで、アプリ開発やAPIセキュリティのためにOpenAPIを用いる理由が明確になっただろう。ここから、主要なメリットを見ていく。
- OpenAPIを用いることで、内部APIの開発が手間のかかる作業でなくなり、統一されたAPIスタイルの生成や再利用性の向上、革新が実現できる。
- 複数の操作が自動化され、快適なAPI開発体験が得られる。
- APIの探索が容易で、ライブラリやSDKなどの追加リソースが提供される。
- OpenAPIはしっかり管理され世界中で採用されているため、APIエコシステムを強力に支援し、他に匹敵する標準は存在しない。
OpenAPIツール
OpenAPIを利用することで得られる数多くのメリットを理解すれば、他のAPI標準に目を向ける余地はない。OpenAPIを採用した後は、利用時やAPI運用のセキュリティ確保に役立つ主要ツールを把握することが重要だ。
これらのツールは、コーディング、テスト、ドキュメント作成など、API開発の各段階をサポートする。
- For Editing
OpenAPIの利用者は、Optic、SwaggerHub、Insomnia Designer、Curio、Stoplight、Visual Studio Code Extensionなど、強力なAPIデザインエディタツールに無制限にアクセスでき、API設計や初期開発を強化できる。
- For documentation
かつて難しかったAPIのドキュメント化も、自動化ツールが豊富に存在するため容易になり、APIの導入やナビゲーションの手間が軽減される。Swagger UI、OpenAPI-Viewer、ReDoc、Widdershinsなどが有用である。
- For Code creation
コーディングを手間なく行うためには、Google Gnostic、OpenAPI Generator、Swagger-Node-CodeGen、Genなどのツールが大いに役立つ。
- For Testing
APIライフサイクルにおけるセキュリティと検証は重要な段階であり、Everest、Postman、Citrus、APIFortressなどのツールが支援する。
- For Deployment
OpenAPI-backendやFastAPIといったツールは、サーバ実装に必要なサポートを提供する。
- For discovery
検索エンジンやディレクトリに向けてOpenAPIファイルをプロファイルする場合、API TrackerやAPIs.guruなどのツールが用いられる。これらディレクトリにAPIを掲載することは、注目を集める有効な方法である。
- For Validation
開発前に、標準のOAS規準に沿って定義と検証を行うことが不可欠であり、OpenAPILintやSpectralなどのツールが支援する。
- For conversion formatting
Odata-OpenAPIやAPI Transformerなどのツールは、異なる仕様間でのAPI変換を迅速化し促進するために設計されている。
- For Management
API管理に関しては、API managementのためのセキュリティ、ホスティング、収益化など主要なタスクを支援するツールが提供され、API UmbrellaやAPImanといった有名なオープンソースツールがある。
結論
API開発者の皆様、主要な開発上の課題を解消し、プロセスを自動化し、エラーなく、簡単かつ迅速に進めたいなら、OpenAPIの利用が一策である。
HTTP APIの定義における標準的手法を提供することで、APIエンジニアや開発者の作業が大いに楽になった。従来の仕様からOpenAPIへ移行するかどうか、是非検討してほしい。OpenAPIは未来を担う技術である。
FAQ
参考資料
最新情報を購読
