ASP.NET Core web API Yardım sayfaları ile Swagger / OpenapıASP.NET Core web API help pages with Swagger / OpenAPI

Tarafından Christoph Nienaber ve Riko SuterBy Christoph Nienaber and Rico Suter

Bir Web API'si kullanılırken, çeşitli metotlarını anlama bir geliştirici için zor olabilir.When consuming a Web API, understanding its various methods can be challenging for a developer. Swaggerolarak da bilinen Openapı, Web API'leri için kullanışlı belgeler ve Yardım sayfaları oluşturma sorununu çözer.Swagger, also known as OpenAPI, solves the problem of generating useful documentation and help pages for Web APIs. Bu, etkileşimli belgeleri, istemci SDK oluşturma ve API keşfedilebilirliğini gibi avantajlar sağlar.It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

Bu makalede, Swashbuckle.AspNetCore ve NSwag uygulamaları .NET Swagger büyütmüş:In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • Swashbuckle.AspNetCore Swagger belgeler için ASP.NET Core Web API'leri oluşturmak için açık kaynak bir projedir.Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • NSwag Swagger belgeler oluşturmak ve tümleştirme için başka bir açık kaynaklı proje Swagger kullanıcı arabirimini veya ReDoc içinde ASP.NET Core web API'leri.NSwag is another open source project for generating Swagger documents and integrating Swagger UI or ReDoc into ASP.NET Core web APIs. Ayrıca, NSwag API'niz için C# ve TypeScript istemci kodu oluşturmak için bir yaklaşım sunar.Additionally, NSwag offers approaches to generate C# and TypeScript client code for your API.

Swagger nedir / Openapı?What is Swagger / OpenAPI?

Swagger belirtimidir tanımlamak için bir dilden REST API'leri.Swagger is a language-agnostic specification for describing REST APIs. Swagger proje için üzerinde Bağış Openapı girişim, burada, artık Openapı adlandırılır.The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as OpenAPI. Her iki birbirinin yerine kullanılır; Ancak, Openapı tercih edilir.Both names are used interchangeably; however, OpenAPI is preferred. Bu hem bilgisayarları hem de bir hizmet uygulaması (kaynak kodu, ağ erişimi, belgeleri) doğrudan erişim olmadan yeteneklerini anlamalarına insanlar sağlar.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). İlişkisi kaldırılan Hizmetleri bağlanmak için gerekli çalışma miktarını en aza bir hedeftir.One goal is to minimize the amount of work needed to connect disassociated services. Başka bir hedefe doğru bir şekilde bir hizmet belgesi için gereken süreyi azaltmaktır.Another goal is to reduce the amount of time needed to accurately document a service.

Swagger belirtimi (swagger.json)Swagger specification (swagger.json)

Swagger akışa çekirdek Swagger belirtimidir—varsayılan olarak, bir belge adlı swagger.json.The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. Hizmet tabanlı Swagger araç zinciri (veya bu üçüncü taraf uygulamaları) tarafından oluşturulur.It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. Bu, API'nizi ve HTTP ile erişmek nasıl yeteneklerini açıklar.It describes the capabilities of your API and how to access it with HTTP. Swagger kullanıcı arabirimini yönlendirir ve araç zinciri tarafından bulma ve istemci kodu oluşturmayı etkinleştirme için kullanılır.It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. Konuyu uzatmamak amacıyla sınırlı bir Swagger belirtimi bir örnek aşağıda verilmiştir: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 kullanıcı ArabirimiSwagger UI

Swagger kullanıcı Arabirimi oluşturulan Swagger belirtimi kullanarak hizmeti hakkında bilgi sağlayan bir web tabanlı bir kullanıcı Arabirimi sunar.Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. ASP.NET Core uygulamanızı bir ara yazılım kayıt çağrısı kullanarak barındırılan Swashbuckle hem NSwag Swagger kullanıcı arabirimini, katıştırılmış bir sürümünü içerir.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 kullanıcı Arabirimi şöyle görünür:The web UI looks like this:

Swagger kullanıcı Arabirimi

Kullanıcı Arabiriminden denetleyicilerinizi her genel bir eylem yöntemi test edilebilir.Each public action method in your controllers can be tested from the UI. Bir yöntem adı bölümü genişletmek için tıklayın.Click a method name to expand the section. Gerekli tüm parametreleri ekleyin ve deneyin! .Add any necessary parameters, and click Try it out!.

Örnek Swagger alma test

Not

Ekran görüntüleri için kullanılan Swagger kullanıcı arabirimini sürüm sürüm 2 ' dir.The Swagger UI version used for the screenshots is version 2. Sürüm 3 örnek için bkz: Petstore örnek.For a version 3 example, see Petstore example.

Sonraki adımlarNext steps