ASP.NET Core（八） 之 Swagger UI 默认参数的坑

小渣渣

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

回顾

ASP.NET Core（七）深入刨析框架源码
https://www.itsvse.com/thread-9601-1-1.html

ASP.NET Core（六）DI 手动获取注入对象的方法
https://www.itsvse.com/thread-9595-1-1.html

ASP.NET Core（五）基于 CAP 分布式事务
https://www.itsvse.com/thread-9593-1-1.html

ASP.NET Core（四）之过滤器统一 ModelState 模型验证
https://www.itsvse.com/thread-9589-1-1.html

ASP.NET Core（三）使用 ActivatorUtilities 动态创建实例
https://www.itsvse.com/thread-9488-1-1.html

ASP.NET Core（二）通过代码自重启应用
https://www.itsvse.com/thread-9480-1-1.html

ASP.NET Core（一）使用 Redis 缓存
https://www.itsvse.com/thread-9393-1-1.html

首先，新建一个 ASP.NET Core 3.1 的项目，使用 nuget 安装 Swashbuckle.AspNetCore 包，命令如下：

登录可见。

在 startup.cs 文件配置 Swagger 服务，如下：

ConfigureServices 方法

登录可见。

Configure 方法

登录可见。

新建一个 Test 控制器，代码如下：

登录可见。

Test 控制器 Create 接口 Product 参数模型对象如下：

登录可见。

启动项目后，访问：http://localhost:18979/swagger/index.html，如下图：



swagger.json 内容如下：

{
  "openapi": "3.0.1",
  "info": {
    "title": "My API",
    "version": "v1"
  },
  "paths": {
    "/api/Test/Create": {
      "post": {
        "tags": [
          "Test"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Information": {
        "type": "object",
        "properties": {
          "isDiscount": {
            "type": "boolean"
          },
          "isVip": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Product": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "disabled": {
            "type": "boolean"
          },
          "info": {
            "$ref": "#/components/schemas/Information"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

我们发现 Boolean 类型和可空 Boolean 类型，默认都是：true，在日常开发中 bool 如果没有赋值默认应该是 false，可空类型默认应该是 null，我们尝试使用 swagger 模拟提交的话，参数不注意的话，很容易出现事故。（上周，我就使用 swagger 模拟提交一个 bool 参数默认是 true 导致将微信消息推送给全体人员）

如何将 Boolean 类型默认赋值成 false 呢？可空类型赋值成 null 呢？

新建一个类继承于 ISchemaFilter，代码如下：

登录可见。

并且在添加 swagger 服务的时候，添加该过滤器 AddSwaggerGen 修改如下：

登录可见。

对于某些特殊 bool 字段，默认值需要设置为 true 的，可以添加 [DefaultValue(true)] 特性即可，如下图：

{
  "name": "string",
  "disabled": true,
  "info": {
    "isDiscount": false,
    "isVip": null
  }
}

swagger.json 文件如下：

{
  "openapi": "3.0.1",
  "info": {
    "title": "My API",
    "version": "v1"
  },
  "paths": {
    "/api/Test/Create": {
      "post": {
        "tags": [
          "Test"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/Product"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Information": {
        "type": "object",
        "properties": {
          "isDiscount": {
            "type": "boolean",
            "default": false
          },
          "isVip": {
            "type": "boolean",
            "default": null,
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Product": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "disabled": {
            "type": "boolean",
            "default": true
          },
          "info": {
            "$ref": "#/components/schemas/Information"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

（完）

飞鱼

学习学习。。。

飞鱼

学习学习，老铁，更新这么多，跟不上了啊

lgf228

RE: ASP.NET Core（八） 之 Swagger UI 默认参数的坑 [修改]
高级模式

qiuyueming

学习学习