Swagger/OpenAPI を使用する ASP.NET Core Web API のドキュメントASP.NET Core web API documentation with Swagger / OpenAPI

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

Swagger (OpenAPI) は REST API を記述するための仕様であり、言語に依存しません。Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. これにより、コンピューターと人間の両方が、ソース コードに直接アクセスせずに REST API の機能を理解できるようになります。It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. 主な目的は次のとおりです。Its main goals are to:

  • 関連のないサービスに接続するために必要な作業量を最小限にします。Minimize the amount of work needed to connect decoupled services.
  • 正確にサービスをドキュメント化するために必要な時間を減らします。Reduce the amount of time needed to accurately document a service.

.NET 用の 2 つの主要な OpenAPI の実装は、SwashbuckleNSwag です。次を参照してください。The two main OpenAPI implementations for .NET are Swashbuckle and NSwag, see:

OpenApi と SwaggerOpenApi vs. Swagger

Swagger プロジェクトは 2015 年に OpenAPI Initiative に寄贈され、それ以降は OpenAPI と呼ばれています。The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. どちらの名前も同じように使用されます。Both names are used interchangeably. ただし、"OpenAPI" は仕様を指します。However, "OpenAPI" refers to the specification. "Swagger" は、オープンソース製品および OpenAPI Specification と協力している SmartBear による商用製品のファミリを指します。"Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. OpenAPIGenerator などの後続のオープンソース製品も Swagger ファミリ名に該当しますが、SmartBear からはリリースされていません。Subsequent open-source products, such as OpenAPIGenerator, also fall under the Swagger family name, despite not being released by SmartBear.

要約すると、次のようになります。In short:

  • OpenAPI は仕様です。OpenAPI is a specification.
  • Swagger は、OpenAPI 仕様を使用するツールです。Swagger is tooling that uses the OpenAPI specification. たとえば、OpenAPIGenerator や SwaggerUI などです。For example, OpenAPIGenerator and SwaggerUI.

OpenAPI の仕様 (openapi.json)OpenAPI specification (openapi.json)

OpenAPI の仕様は、API の機能について説明されているドキュメントです。The OpenAPI specification is a document that describes the capabilities of your API. そのドキュメントは、コントローラーとモデル内の XML および属性の注釈に基づいています。The document is based on the XML and attribute annotations within the controllers and models. それは OpenAPI フローの中核部分であり、SwaggerUI などのツールを駆動するために使用されます。It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. 既定では、openapi.json という名前になっています。By default, it's named openapi.json. 簡略化された OpenAPI の仕様の例は次のとおりです。Here's an example of an OpenAPI specification, reduced for brevity:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UISwagger UI

Swagger UI には、生成された OpenAPI の仕様を使用してサービスに関する情報が提供される Web ベースの UI が用意されています。Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI 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. メソッドの名前を選択してセクションを展開します。Select a method name to expand the section. 必要なパラメーターを追加し、 [Try it out!](試してみる) を選択します。Add any necessary parameters, and select 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