12月に、SwaggerHubの強力な新機能「API標準化」をリリースしました。これにより、チームはAPIスタイルガイドラインを大規模に構築し、適用できるようになります。
年末年始に、無料トレーニング「SwaggerでAPI標準を大規模に構築・適用する」を開催しました。60分間のセッションでは、新機能のライブデモンストレーションを行い、SwaggerツールとOpenAPI仕様を使用して組織がAPI設計を標準化する方法について議論しました。
1,000人以上がセッションに参加し、チームがSwaggerHubとOASを使ってこれらの戦略を実行に移す方法について、多くの質問を受けました。しかし、年末の忙しさでウェビナーに参加できなかったという声も多く聞かれました。
1月10日にウェビナーの特別再放送を開催することを発表できることを嬉しく思います！プレビューとして、最初のセッションからのトップ質問を共有し、回答したいと思います。以下の質問を確認し、1月10日午前10時および午後2時（東部時間）のウェビナーの席を予約することを忘れないでください。
SwaggerHubの新しいAPI標準化機能は、内部スタイルガイドからのカスタムルールを追加するオプションをサポートしていますか？
この機能は、初期リリースではサポートされていません。API標準化に追加してほしいルールがある場合は、Twitterの@swaggerhubまでご連絡ください。APIチームのニーズを満たすためにツールを進化させ続けるために、皆様からのフィードバックを求めています。
SwaggerHubでAPI標準化を有効にすると、すべてのAPIと各APIバージョンに適用されますか？
API標準化では、組織レベルでルールを設定し、それらのルールをSwaggerHubカタログ内のすべてのAPI定義に適用できます。定義の新しいバージョンを作成したり、既存のバージョンを更新したりすると、この機能は自動的に検証を行い、アカウントで定義されたルールに基づいてフィードバックを提供します。
API標準化は、OpenAPI仕様の最新バージョン、OAS 3.0で機能しますか？
はい、API標準化は、いくつかのルール例外を除いてOAS 3.0をサポートしています。以下にルールと例外の全リストを示します。
オペレーション
-
Summaryは大文字で始まり、ピリオドで終わる必要があります
-
Operation descriptionは存在し、空でない文字列である必要があります
-
Operationはタグと空でない文字列を持つ必要があります（OpenAPI 2.0のみ）
-
Operationは1つのタグのみを持つ必要があります
-
Operationは少なくとも1つの2xxレスポンスを持つ必要があります
API情報
-
APIタイトルは存在し、空でない文字列である必要があります
-
API descriptionは存在し、空でない文字列である必要があります
-
API連絡先は存在し、空でない文字列である必要があります
モデル
コードから定義を生成する方法についてアドバイスはありますか？既存のAPIで有用なインターフェースを生成するのに苦労しています。
既存のAPIからOpenAPI定義を生成するのに役立つオープンソースツールやライブラリがあります。Swaggerチームは、既存のAPIからOASを生成するためのいくつかのライブラリをサポートしており、残りはOASコミュニティによって維持されています。
OASをサポートする他のオープンソースツールはこちらで確認できます。
複数の仕様ファイル間で共通のモデルを作成して参照できますか？
この機能は、SwaggerHubのドメイン機能を通じてサポートされています。ドメインは、SwaggerHubに保存され、SwaggerHubエディターから定義内で参照できる再利用可能なコンポーネントです。
ドメインは、以下のコンポーネント（任意の組み合わせ）を含めることができます。
詳細はこちら
SwaggerHubはソース管理リポジトリと連携できますか？
SwaggerHubは、GitHub、Bitbucket、GitLabとのソース管理統合を提供しています。この統合により、API定義、自動生成されたサーバーコード、またはクライアントSDKを既存のリポジトリと同期できます。同期は、SwaggerHubでAPIを保存するたびに行われます。ターゲットリポジトリに追加、更新、または無視されるファイルを完全に制御できます。
さまざまなGitHubのリポジトリやブランチにOAS定義をホストする代わりに、SwaggerHubをすべてのAPI設計とドキュメントのニーズの唯一の真実のソースとして活用し、同時にGitHubまたは他のソース管理リポジトリのソースコードと同期させることができます。
詳細はこちら
APIの品質を判断するために、どのような測定基準を使用すべきですか？
ウェビナーでは、2019年1月に公開される2019年APIレポートの新しいデータをプレビューしました。組織が品質を測定する方法については、上位3つの回答は、パフォーマンス、使いやすさ/開発者エクスペリエンス、稼働時間/可用性でした。また、高品質なAPIを提供するために使用されるトップツールは、APIドキュメントツール、API機能テストツール、CI/CDツールであることがわかりました。
1月にレポートからより多くの洞察を共有します。これには、計画と設計からテストと監視までのAPIライフサイクル全体における品質に関する詳細な見解が含まれます。
SwaggerとOpenAPIの違いは何ですか？
SwaggerとOpenAPI仕様の関係を理解する最も簡単な方法は次のとおりです。
この仕様は、OpenAPIイニシアチブの下でLinux Foundationに寄贈された後、2015年に正式に改名されました。
詳細はこちら
既存のAPIに行われた変更を確認できますか？それらの変更を受け入れる前にレビューするプロセスはありますか？
SwaggerHubは、API定義の複数のバージョンをホストおよび維持する機能を提供します。これにより、開発準備が整った公開バージョンを持ち、APIが進化するにつれて定義の次のバージョンを開発し続けることができます。
チームがAPI定義に行われた変更を追跡する方法の1つは、SwaggerHubエディターのコメント機能を使用することです。これにより、エディター内から直接フィードバックを追加したり、変更を要求したり、問題を解決したりできます。
APIへの変更をレビューしてマージする場合、チームはSwaggerHubの比較＆マージ機能を活用できます。この機能を使用すると、作業中の定義バージョンと元の公開バージョンとの変更を比較できます。アーキテクトまたはマネージャーとして、行われた変更を視覚的に確認し、変更を受け入れるか拒否するかを選択できます。定義全体で適用したいとわかっている一連のルールがあり、これらの更新を手動でレビューしてマージしたくない場合は、組織設定のAPI標準化パネルでルールを選択できます。
私たちはCIパイプラインでコードファーストのアプローチで作業しています。コードからswaggerを生成し、それをAPIに送信し、ルールに従って有効かどうかを示す応答を取得する自動テストを行うことは可能ですか？
多くのチームや組織がSwaggerhubをWebインターフェース経由で利用していますが、プラットフォームの基盤となるAPIも同様に強力です。コードのアノテーションやフレームワークを通じてOpenAPIを動的に生成している場合、レジストリAPIへの簡単なPOST呼び出しにより、定義を検証し、より大規模な内部カタログの一部として保存できます。このワークフローは、新しい定義の提出を簡単にするだけでなく、テストやドキュメントのために定義を引き出すプロセスも簡単にします。私たちが「コードファースト」へのアプローチをより詳しく探求することに興味がある場合、最近のウェビナーでは、提供されているワークフローとプラグインの一部を取り上げました。
詳細はこちら
新しいAPI標準化機能を実際に見てみませんか？1月10日の特別ウェビナー再放送にご参加ください。今すぐ登録