Swagger/openapı ile web apı 'si belgelerini ASP.NET Core

Sağlayan- Christoph Nienaber ve Riko Suter

Swagger (Openapı), REST API 'Leri açıklamak için dilden bağımsız bir belirtimdir. Hem bilgisayarların hem de insanların kaynak koda doğrudan erişim olmadan bir REST API yeteneklerini anlamasına imkan sağlar. Ana amaçları şunlardır:

• Ayrılmış hizmetlere bağlanmak için gereken iş miktarını en aza indirin.
• Bir hizmeti doğru bir şekilde belgelemek için gereken süre miktarını azaltın.

.NET için iki ana Openapı uygulaması, swashbuckle ve nswag' dir, bkz.:

• Swashbuckle ile çalışmaya başlama
• NSwag ile çalışmaya başlama

Openapı ile Swagger

Swagger projesi, 2015 ' de Openapı girişimi 'ne bağlılmıştı ve bu yana Openapı olarak adlandırılmıştı. Her iki ad birbirinin yerine kullanılır. Ancak, "OpenAPI" belirtiye başvurur. "Swagger", Openapı belirtimiyle birlikte çalışan, Smartden açık kaynaklı ve ticari ürünlerin ailesini ifade eder. Openapigeneratorgibi sonraki açık kaynaklı ürünler, Ayrıca, akıllı pul tarafından yayımlanmamasına rağmen Swagger aile adı altına düşdü.

Kısacası:

• Openapı bir belirtimdir.
• Swagger, Openapı belirtimini kullanan araçlama araçları. Örneğin, OpenAPIGenerator ve SwaggerUI.

Openapı belirtimi (openapi.json)

Openapı belirtimi, API 'nizin yeteneklerini açıklayan bir belgedir. Belge, denetleyiciler ve modeller içindeki XML ve öznitelik ek açıklamalarını temel alır. Openapı akışının temel parçasıdır ve SwaggerUI gibi araçları sağlamak için kullanılır. Varsayılan olarak, openapi.jsolarak adlandırılır. Aşağıda, breçekimi için azaltılmış bir Openapı belirtimi örneği verilmiştir:

{
  "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 Kullanıcı arabirimi

Swagger Kullanıcı arabirimi , oluşturulan openapı belirtimini kullanarak hizmet hakkında bilgi sağlayan Web tabanlı bir kullanıcı arabirimi sunar. hem swashbuckle hem de nswag, Swagger kullanıcı arabirimi 'nin ekli bir sürümünü içerir, böylece bir ara yazılım kayıt çağrısı kullanarak ASP.NET Core uygulamanızda barındırılabilmesini sağlayabilirsiniz. Web Kullanıcı arabirimi şöyle görünür:

Denetleyicilerinizdeki her genel eylem yöntemi kullanıcı arabiriminden test edilebilir. Bölümü genişletmek için bir yöntem adı seçin. Gerekli parametreleri ekleyin ve deneyin! seçeneğini belirleyin.

Sonraki adımlar

• Swashbuckle kullanmaya başlama
• NSwag kullanmaya başlama