Swagger扩展为你"添油加气"

关注架构师高级俱乐部

开启架构之路

不定期福利发放哦~

Leon

读完需要

4

分钟

速读仅需 2 分钟

介绍一款Swagger扩展

日常接口开发中都需要用到Swagger来生成接口文档并用 Swagger 自带支持的模拟请求进行测试，但是需要支持认证或者上传文件等操作需要自行去按接口进行开发才可支持，现在介绍一款封装了 Swagger 的中间件来避免一些繁琐的操作即可支持常用功能

1

   

如何使用

• 安装 NetPro.Swagger

执行以下命令或者 Nuget 包管理器中搜索安装最新版

Install-Package NetPro.Swagger  -Version 3.1.6 

• Swagger 注入

public void ConfigureServices(IServiceCollection services,IConfiguration configuration) 
{ 
     services.AddNetProSwagger(configuration); 
} 
 
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) 
{ 
      app.UseNetProSwagger(); 
}

‍

• 输出 XML 文档

相关类库 csproj 工程文件中加入以下配置

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">    
<DocumentationFile>bin\Debug\netcoreapp3.1\程序集名称.xml</DocumentationFile> 
 </PropertyGroup>

运行没有任何反应，这时候需要在 appsetting.json 配置文件中加入相关配置

"SwaggerOption": { 
    "Enable": true,//是否开启Swagger 
    "RoutePrefix": "swagger", 
    "Description": "this is swagger for netcore", 
    "Title": "Demo swagger", 
    "Version": "first version", 
    "TermsOfService": "netcore.com", 
    "Contact": { 
      "Email": "swagger@netcore.com", 
      "Name": "swagger", 
      "Url": "swagger@netcore.com" 
    }, 
    "License": { 
      "Name": "", 
      "Url": "" 
    }    
  }

再次执行dotnet run 命令运行，可以看见右上角默认支持认证，点击输入 jwt 即可

2

   

支持功能

2.1

   

暗黑主题

SwaggerOption 配置节点中增加 IsDarkTheme 等于 true 即可

 "IsDarkTheme": true,

2.2

   

文件上传按钮

请求参数类型为 IFormFile，Swagger 会自动识别为为其添加文件按钮

    /// <summary>
    /// 单文件
    /// </summary>
    public IFormFile File { get; set; }

2.3

   

添加公共 Url 参数

一般接口会有一些公共参数，但一般接口内部不会用到，例如签名参数，就没必要每个请求实体都包含这些业务接口不使用的参数，可以通过以下节点添加 swagger 公共参数还不污染请求实体

"Query": [ //swagger默认url公共参数 
      { 
        "Name": "sign", 
        "Description": "签名" 
      }, 
      { 
        "Name": "timestamp", 
        "Description": "客户端时间戳" 
      } 
    ]

2.4

   

添加公共头参数

添加以下配置节点即可把公共参数添加进 swagger 头信息

 "Headers": [ //swagger默认头参数 
      { 
        "Name": "User", 
        "Description": "用户" 
      } 
    ],

就是这么简单,swagger功能都通过appsetting.json配置即可。

此库只是NetPro项目下的一个扩展功能，其中还包括很多其他常用组件与开箱即用打包所有组件的NetPro.Web.Api组件更加方便容易的开发Api接口

项目地址：

https://github.com/LeonKou/NetPro https://github.com/LeonKou/NetPro.Swagger

github