（四）如何在.NET Core 3.x 中使用Swagger

最新推荐文章于 2022-07-07 17:35:16 发布

置顶

知更鸟的码

最新推荐文章于 2022-07-07 17:35:16 发布

阅读量571

点赞数 1

分类专栏： .Net Core .NET高级开发文章标签： c#

本文链接：https://blog.csdn.net/ananlele_/article/details/107488261

版权

本文档介绍了如何在.NET Core 3.1 Web API项目中使用Swagger，包括Swagger/OpenAPI规范、Swagger UI的使用，以及如何通过Swashbuckle将Swagger集成到项目中，提供API接口文档的自动化生成。文章还讲述了如何添加令牌头以处理授权问题。

摘要由CSDN通过智能技术生成

在服务端开发过程中，特别是在前后端分离的项目中，后端人员往往会提供出来很多API接口供前端人员使用。一般后端人员会在开发接口的过程中同时维护一份文档（如word、excel），用来说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。但是这种传统的API书写方式很费时间，而且容易造成因为接口文档更新不及时导致的前后端交流成本增加的问题。

基于上述情况，诞生了许多API接口文档自动化生成工具，如Swagger、I/O Docs、apiary.io、Docco、Dexy、Doxygen、TurnAPI。今天重点来说说目前非常流行且实用的用于生成API接口文档的框架Swagger。

Swagger/OpenAPI

Swagger是用于描述REST API的规范，Swagger项目捐赠给了OpenAPI Initiative，现在称为OpenAPI，这两个名称可以互换使用。但是，首选OpenAPI。它使我们都可以理解服务的功能，而无需直接查看实际的实现代码（源代码，网络访问，文档）。Swagger减少了集成API时所需的工作量。同样，它还帮助API开发人员快速，准确地记录其API。

Swagger/OpenAPI规范（Swagger.json或openapi.json）

OpenAPI流程的核心是规范，也就是说Swagger规范是Swagger流程的重要组成部分，默认情况下，Swagger工具会基于我们的API生成名为swagger.json或openapi.json的文档。它是由OpenAPI工具链（或其第三方实现）根据您的服务生成的。它描述了我们API的功能以及如何通过HTTP访问它。它驱动Swagger UI，工具链使用它来启用发现和客户端代码生成。以下是一个简化的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&#