Strony sieci web platformy ASP.NET Core pomocy interfejsu API, w strukturze Swagger / interfejsu OpenAPIASP.NET Core web API help pages with Swagger / OpenAPI

Przez Christoph Nienaber i Rico SuterBy Christoph Nienaber and Rico Suter

Podczas korzystania z internetowego interfejsu API, informacje o jego różne metody może stanowić wyzwanie dla dewelopera.When consuming a Web API, understanding its various methods can be challenging for a developer. Struktury swagger, znane również jako OpenAPI, rozwiązuje problem Generowanie przydatne stron pomocy i dokumentacji dla interfejsów API sieci Web.Swagger, also known as OpenAPI, solves the problem of generating useful documentation and help pages for Web APIs. Zapewnia korzyści, takich jak dokumentacja interaktywne, generowanie zestawów SDK klienta i odnajdywania interfejsu API.It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

W tym artykule Swashbuckle.AspNetCore i NSwag implementacji .NET Swagger są pokazywane:In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • Swashbuckle.AspNetCore to projekt typu open source do generowania dokumentów struktury Swagger dla interfejsów API sieci Web programu ASP.NET Core.Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • NSwag inny projekt open source do generowania dokumentów struktury Swagger i integrowanie interfejs użytkownika struktury Swagger lub ReDoc do platformy ASP.NET Core internetowych interfejsów API.NSwag is another open source project for generating Swagger documents and integrating Swagger UI or ReDoc into ASP.NET Core web APIs. Ponadto NSwag oferuje podejścia, aby wygenerować C# i TypeScript kodu klienta dla interfejsu API.Additionally, NSwag offers approaches to generate C# and TypeScript client code for your API.

Co to jest struktury Swagger / OpenAPI?What is Swagger / OpenAPI?

Struktury swagger jest niezależny od języka opisu REST interfejsów API.Swagger is a language-agnostic specification for describing REST APIs. Projekt struktury Swagger zostało przekazanych inicjatywy OpenAPI, gdzie go jest teraz nazywana interfejsu OpenAPI.The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as OpenAPI. Obie nazwy są używane zamiennie. preferowane jest jednak interfejsu OpenAPI.Both names are used interchangeably; however, OpenAPI is preferred. Umożliwia on zarówno komputerów, jak i ludzi, aby zapoznać się z funkcjami usługi bez żadnych bezpośredni dostęp do implementacji (kod źródłowy, dostępu do sieci, dokumentacji).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). Jeden cel jest minimalizacja ilości pracy wymaganej do nawiązywania połączenia z usługami usunięte skojarzenia.One goal is to minimize the amount of work needed to connect disassociated services. Innym celem jest skrócenie czasu wymaganego do dokładnie dokumentu usługi.Another goal is to reduce the amount of time needed to accurately document a service.

Specyfikacja swagger (swagger.json)Swagger specification (swagger.json)

Core do usługi flow struktury Swagger jest specyfikacja Swagger—domyślnie o nazwie dokumentu swagger.json.The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. Jest ona generowana przez struktury Swagger narzędzie łańcucha (lub innych implementacji go) na podstawie Twojej usługi.It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. Opisuje funkcje interfejsu API i uzyskiwania dostępu do niego za pośrednictwem protokołu HTTP.It describes the capabilities of your API and how to access it with HTTP. Jej dyski interfejsu użytkownika programu Swagger i jest używany przez łańcuch narzędzi, aby umożliwić generowanie kodu klienta wykrywania i.It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. Oto przykład specyfikacji Swagger, zmniejszone dla zwięzłości: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

Interfejs użytkownika struktury swagger oferuje oparte na sieci web interfejs użytkownika, który zawiera informacje dotyczące usługi, za pomocą wygenerowanego specyfikacją struktury Swagger.Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. Zarówno pakiet Swashbuckle, jak i NSwag obejmują wbudowana wersja interfejs użytkownika struktury Swagger, dzięki czemu mogą być hostowane w aplikacji platformy ASP.NET Core przy użyciu wywołania rejestracji oprogramowania pośredniczącego.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. Internetowy interfejs użytkownika wygląda następująco:The web UI looks like this:

Swagger UI

W interfejsie użytkownika można przetestować każdej metody akcji publicznych w kontrolerach.Each public action method in your controllers can be tested from the UI. Kliknij nazwę metody, aby rozwinąć sekcję.Click a method name to expand the section. Dodaj wszystkie niezbędne parametry, a następnie kliknij przycisk wypróbuj! .Add any necessary parameters, and click Try it out!.

Przykład testu pobrać programu Swagger

Uwaga

Wersja interfejs użytkownika struktury Swagger, umożliwiający zrzuty ekranu jest w wersji 2.The Swagger UI version used for the screenshots is version 2. Na przykład w wersji 3, zobacz przykład Petstore.For a version 3 example, see Petstore example.

Następne krokiNext steps