【译】ASP.NET Core Web API文档（Swagger/OpenAPI）

原文链接：传送门。

Swagger（OpenAPI）是一个语言无关的用来描述Rest API的规范。它允许计算机和人都可以理解Rest API的能力，而不用直接访问API的源代码。它的主要目标是：

• 最小化连接解耦的服务的所需的工作量
• 减少准确文档化一个服务所需要的时间

对于.NET平台两个主要的OpenAPI实现是 Swashbuckle 和 NSwag，请查看：

• Getting Started with Swashbuckle
• Getting Started with NSwag

OpenAPI 与 Swagger的对比

Swagger项目在2015年被捐赠给OpenAPI倡议，此后也被称为OpenAPI。这两个名字现在几乎可以互换使用。然而，“OpenAPI”指的是规范。Swagger指的是来自于SmartBear的开源及商业产品家族，其与OpenAPI规范协同工作。后续的开源产品，例如OpenAPIGenerator，也归并到Swagger家族名称之下，尽管其不是SmartBear公司发布的。

简而言之：

• OpenAPI 是一个规范
• Swagger是使用OpenAPI规范的工具。比如 OpenAPIGenerator 和 SwaggerUI

OpenAPI规范（openapi.json）

OpenAPI是描述了你的API的能力的一个文档。这个文档是基于XML以及在控制器及方法内的属性标记的。它是OpenAPI的核心部分并且被用来驱动例如SwaggerUI这样的工具。默认的，其被命名为openapi.json。这儿有OpenAPI规范的一个示例，为了简洁我们减少了其篇幅。

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

Swagger UI提供了基于Web的UI，其使用生成的OpenAPI规范提供了关于服务的信息。Swashbuckle 和NSwag都包含了一个Swagger UI的嵌入式版本，因此其可以使用一个中间件注册调用被寄宿在你的ASP.NET Core App中。其Web UI看起来像是这样：

 

你的控制器中的各个方法都可以从UI中进行测试。选中方法名称来展开这个节点，添加任何必要的参数，然后选择Try it Out。

 

 下一步/额外资源

• Get started with Swashbuckle
• Get started with NSwag