素晴らしいAPIを構築しようと決めたのですね…素晴らしい！それとも、すでにAPIをお持ちですか…さらに素晴らしい！
APIの定義を作成することは、API開発において重要なステップですが、見過ごされがちです。API定義（API仕様または記述形式と呼ばれることもあります）は、機械が読み取り可能な形式でAPIを記述するためのフォーマットを提供するように設計されています。これらは言語に依存しないため、どの言語を選択してもその恩恵を受けることができます。
今日、APIに最も一般的に使用されている定義は、OpenAPI Specificationです。OpenAPI Specification（OAS）は、オリジナルのSwagger Specificationに基づき、APIのRESTful標準を定義します。OAS定義は、APIのリソースと操作をマッピングします。
この記事では、定義を作成するメリットと、作業を容易にするために使用できるツールについて説明します。
定義を作成する理由
API定義は以下に使用できます
- 社内の関係者がAPIを理解し、その属性について合意するのを支援する: これは前職の会社にとって強力なものでした。API定義により、Swagger UIのようなドキュメンテーションツールがAPIを視覚化できます。当社では、Swagger UIを使用してすべての内部APIを視覚化し、開発者が上流および下流のサービスを迅速かつ容易に利用できるようにしました。SwaggerHubには、APIの設計、表示、共同作業を行うためのチームおよびエンタープライズレベルの機能があります。
- 外部の人がAPIとその機能について理解するのを助ける: 再度、Swagger UIはドキュメント化のためのよく使われる視覚化ツールであり、私のお気に入りはマーベルAPIです。API定義ファイルを入力として使用する、ReDoc、ReadMe、Slateなどのクールなドキュメントソリューションもあります。
- APIのテストを作成する: OAS定義は、誰かがAPIを呼び出したときにどのような応答が得られるかを記述するコントラクトを提供します。このコントラクトは、テストケースを作成するために再利用できます。これにより、APIをテストするために必要なセットアップチームの時間を大幅に削減できます。ReadyAPIを使用して、API定義から機能テスト、ロードテスト、セキュリティスキャンを実行し、APIを仮想化することができます。そして、API定義をインポートすることで、これらすべてを開始できます。
- 実装コードとSDKの生成: ドキュメントの生成に加えて、OpenAPI定義は実装コードとSDKを作成することで開発を加速するために使用できます。API定義ファイルは、Swagger CodegenやSwaggerHubなどのさまざまなツールにインポートできます。これらは、Java、Scala、Rubyなど、さまざまな言語でコードを作成できます。実装コードを作成することで、APIコードをゼロから記述する必要がなくなります。
- APIをライブにする: Amazon API Gateway、Azure、Apigee、またはGoogle CloudのようなAPIゲートウェイはすべて、API定義を使用してライブAPIを作成します。
- APIを監視する: 理想的には、顧客が気づく前にAPIに問題があるかどうかを知りたいものです。Alertsiteのようなツールに定義をインポートすると、APIは自動的に監視されます。
API定義は、APIの信頼できる情報源として機能するはずです。APIの実装、APIの文書化、およびAPIの成功を確実にするために必要なツールの提供に使用できます。
API定義の作成
定義を作成する理由を説明しましたので、その方法についていくつかの手法を説明します。いくつかの選択肢があります
- 最初にAPIを設計し、オプションで定義から実装コードを作成する
- APIを呼び出し、そのリクエストを使用して定義を作成する
- コードに定義を生成させる
1. まず定義を作成する（そして実装する）
「デザインファースト」アプローチは、コードを記述する前にAPI定義を最初に記述することを提唱しています。これは比較的新しいアプローチですが、急速に普及しています。実装が完了した後に問題を捕捉するよりも、コードを記述する前に設計上の問題を捕捉する方が効率的です。
SwaggerHubのようなチームベースのツールは、APIの設計と共同作業のための優れた機能を提供します。管理者レベルの権限を設定し、ユーザーが定義の変更を作成およびマージできるようにし、ビジュアルエディタを利用できます。また、OpenAPI準拠の定義の作成方法を学習し、テキストエディタを使用してYAMLファイルを作成することもできます。追加のツールが必要で、SwaggerHubを使用しない場合は、Swagger-Editorで編集、Swagger-UIでドキュメント化、Swagger-Validatorで定義を検証できます。
定義を作成したら、APIの実装コードを作成できます。SwaggerHubは、実装コード（サーバスタブ）の作成を容易にします。また、同様の目的で、オープンソースライブラリのSwagger-Coreも使用できます。定義だけでは記述できないビジネスロジックを追加する必要があります。API定義が変更されるたびに実装コードを作成するようにプロセスを設定できます。
2. Swagger Inspectorを使用してAPI呼び出しから定義を作成する
すでにAPIを実装している（少なくとも部分的に）場合は、Swagger InspectorからAPIにリクエストを行うだけです。
Swagger Inspectorは、APIリクエストを実行し、応答を検証し、OpenAPI定義を作成できます。既存のAPIのドキュメントは、エンドポイントを呼び出し、それらを選択し、[API定義の作成]をクリックすることで作成できます。
これにより、選択したエンドポイントのOpenAPIファイルが自動的に生成され、貴重な開発時間を節約できます。定義はSwaggerHubに無料で保存され、APIのドキュメントにすぐにアクセスできます。ファイルをエクスポートしてクライアントSDKを作成することもできます。
この方法はAPIのスナップショットを作成しますが、APIがそれほど変更されない場合は問題ありません！これはおそらくAPI定義を作成する最も速い方法であり、新しい製品であるSwagger Inspectorを使用するため、私のお気に入りです。提案がある場合は、右下のウィジェットにフィードバックを残してください！
3. コード生成された定義
コードからAPI定義を生成するのに役立ついくつかのプロジェクトがあります。SmartBearで最も時間を費やしたプロジェクトは、Java 7または8とmaven 3.0.4以降で使用できるSwagger-Coreです。SmartBearは、コードに基づいて定義を作成するScalaおよびJavascriptプロジェクトにも貢献しています。別の言語を使用している場合でも、少し検索すればライブラリを見つけることができるでしょう。たとえば、SwashBuckleは、同じことができる.NETライブラリです。
コードから定義を作成することは、優れた方法です。これにより、定義が実装と一貫していることが保証されます。これにはいくつかの課題が伴います。たとえば、定義に人間が理解できる説明と例があることを確認する必要があります。専任のテクニカルライターがいる場合は、開発者と密接に協力してこのアプローチをうまく機能させるべきです。
どのオプションを選択しても、これらのヒントが素晴らしいAPIの作成に役立つことを願っています！