Swagger / Open API を使用する ASP.NET Core Web API のヘルプ ページASP.NET Core Web API help pages with Swagger / Open API

作成者: Christoph Nienaber および Rico SuterBy Christoph Nienaber and Rico Suter

Web API を使用する場合、さまざまなメソッドを理解することは開発者にとって困難な場合があります。When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger (Open API とも呼ばれる) では、Web API の役立つドキュメントとヘルプ ページの生成に関する問題を解決します。Swagger, also known as Open API, solves the problem of generating useful documentation and help pages for Web APIs. Swagger では、対話型のドキュメント、クライアント SDK の生成、API の発見可能性などの利点を提供します。It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

この記事では、Swashbuckle.AspNetCoreNSwag .NET Swagger の実装を示します。In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • Swashbuckle.AspNetCore は、ASP.NET Core Web API の Swagger ドキュメントを生成するためのオープン ソース プロジェクトです。Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • NSwag は、Swagger UIReDoc を ASP.NET Core Web API に統合するためのもう 1 つのオープン ソース プロジェクトです。NSwag is another open source project for integrating Swagger UI or ReDoc into ASP.NET Core Web APIs. ここでは、API 用に C# および TypeScript のクライアント コードを生成するための手段が提供されます。It offers approaches to generate C# and TypeScript client code for your API.

Swagger / Open API とはWhat is Swagger / Open API?

Swagger は、REST API を記述するために、言語に関係なく使える仕様です。Swagger is a language-agnostic specification for describing REST APIs. Swagger プロジェクトは、現在、Open API と呼ばれている OpenAPI イニシアティブに寄贈されました。The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as Open API. どちらの名前も同様に使用できますが、Open API の使用をお勧めします。Both names are used interchangeably; however, Open API is preferred. Open API では、実装 (ソース コード、ネットワーク アクセス、ドキュメント) に直接アクセスすることなく、コンピューターと人間の両方がサービスの機能を理解できます。It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). 関連付けられていないサービスに接続するために必要な作業量を最小限にすることが 1 つの目標です。One goal is to minimize the amount of work needed to connect disassociated services. もう 1 つの目標は、正確にサービスをドキュメント化するために必要な時間を減らすことです。Another goal is to reduce the amount of time needed to accurately document a service.

Swagger 仕様 (swagger.json)Swagger specification (swagger.json)

Swagger フローの基本は、Swagger 仕様です—既定では、ドキュメントの名前は swagger.json です。The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. この仕様は、使用しているサービスに基づいて Swagger ツール チェーン (またはサード パーティによるその実装) によって生成されます。It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. ここでは API の機能と HTTP を使用してアクセスする方法について説明します。It describes the capabilities of your API and how to access it with HTTP. これにより Swagger UI が駆動され、検出とクライアント コードの生成が行えるように、ツール チェーンによって使用されます。It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. 簡略化された Swagger 仕様の例は次のとおりです。Here's an example of a Swagger specification, reduced for brevity:

{
   "swagger": "2.0",
   "info": {
       "version": "v1",
       "title": "API V1"
   },
   "basePath": "/",
   "paths": {
       "/api/Todo": {
           "get": {
               "tags": [
                   "Todo"
               ],
               "operationId": "ApiTodoGet",
               "consumes": [],
               "produces": [
                   "text/plain",
                   "application/json",
                   "text/json"
               ],
               "responses": {
                   "200": {
                       "description": "Success",
                       "schema": {
                           "type": "array",
                           "items": {
                               "$ref": "#/definitions/TodoItem"
                           }
                       }
                   }
                }
           },
           "post": {
               ...
           }
       },
       "/api/Todo/{id}": {
           "get": {
               ...
           },
           "put": {
               ...
           },
           "delete": {
               ...
   },
   "definitions": {
       "TodoItem": {
           "type": "object",
            "properties": {
                "id": {
                    "format": "int64",
                    "type": "integer"
                },
                "name": {
                    "type": "string"
                },
                "isComplete": {
                    "default": false,
                    "type": "boolean"
                }
            }
       }
   },
   "securityDefinitions": {}
}

Swagger UISwagger UI

Swagger UI では、生成された Swagger 仕様を使用して、サービスに関する情報を提供する Web ベースの UI を提供します。Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. ミドルウェアの登録呼び出しを使用して ASP.NET Core アプリでホストすることができるように、Swashbuckle と NSwag の両方に埋め込みバージョンの Swagger UI が含まれます。Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. Web UI は次のようになります。The web UI looks like this:

Swagger UI

コントローラー内の各パブリック アクション メソッドを UI からテストすることができます。Each public action method in your controllers can be tested from the UI. メソッドの名前をクリックし、セクションを展開します。Click a method name to expand the section. 任意の必要なパラメーターを追加し、[Try it out!] をクリックします。Add any necessary parameters, and click Try it out!.

Swagger GET テストの例

注意

スクリーンショットに使用される Swagger UI バージョンは、バージョン 2 です。The Swagger UI version used for the screenshots is version 2. バージョン 3 の例については、Petstore の例に関するページを参照してください。For a version 3 example, see Petstore example.

次の手順Next steps