ASP.NET Core webového rozhraní API pomocí Swaggeru / OpenAPI

Předávkující Nienaber aRiko Suter

Swagger (OpenAPI) je jazyková specifikace pro popisování rozhraní REST API. Umožňuje počítačům i lidem porozumět možnostem REST API bez přímého přístupu ke zdrojovému kódu. Jejím hlavním cílem je:

• Minimalizujte množství práce potřebné k propojení oddělených služeb.
• Zkrátit dobu potřebnou k přesnému zdokumentovat službu.

Dvě hlavní implementace OpenAPI pro .NET jsou Swashbuckle a NS windows, viz:

• Začínáme s Swashbuckle
• Začínáme s NS tesáky

OpenApi vs. Swagger

Projekt Swagger byl v roce 2015 dován iniciativě OpenAPI Initiative a od té doby se označuje jako OpenAPI. Oba názvy se používají zaměnitelně. "OpenAPI" ale odkazuje na specifikaci. "Swagger" označuje rodinu open source a komerčních produktů od SmartBear, které pracují se specifikací OpenAPI. Další open-source produkty, jako je OpenAPIGenerator,spadají také pod název skupiny Swagger, i když ho smartBear nevydá.

Zkráceně:

• OpenAPI je specifikace.
• Swagger je nástroj, který používá specifikaci OpenAPI. Například OpenAPIGenerator a SwaggerUI.

Specifikace OpenAPI (openapi.json)

Specifikace OpenAPI je dokument, který popisuje možnosti vašeho rozhraní API. Dokument je založen na anotacích XML a atributů v rámci kontrolerů a modelů. Je základní součástí toku OpenAPI a používá se k řízení nástrojů, jako je SwaggerUI. Ve výchozím nastavení má název openapi.json. Tady je příklad specifikace OpenAPI, která je pro zkrácení redukce:

{
  "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
      }
    }
  }
}

Uživatelské rozhraní Swaggeru

Swagger UI nabízí webové uživatelské rozhraní, které poskytuje informace o službě pomocí vygenerované specifikace OpenAPI. Swashbuckle i NSuckle obsahují vloženou verzi uživatelského rozhraní Swaggeru, aby ji bylo možné hostovat ve vaší aplikaci ASP.NET Core pomocí volání registrace middlewaru. Webové uživatelské rozhraní vypadá takhle:

Každou metodu veřejné akce v kontrolerů je možné testovat z uživatelského rozhraní. Výběrem názvu metody rozbalte oddíl . Přidejte potřebné parametry a vyberte Vyzkoušet!.

Další kroky

• Začínáme se službou Swashbuckle
• Začínáme se službou NSwag