Asp.Net Core遇到Swagger(一)-Swashbuckle基础篇

共 4966字,需浏览 10分钟

 ·

2021-09-05 18:10

点击上方蓝色字体,关注我们


1


前言


作为一名后端,接口开发好了,与前端对接或者三方公司进行对接时,每次反反复复的依靠人力构建接口说明文档,每一次接口变更,输入输出结果字段变化,不胜其烦,能依据接口动态生成api对接文档岂不是更好,有变更,重新生成一下项目就好,还能在线调试接口,后端可控粒度高,你一定脑子里闪过Swagger,废话不多说,冲~



2


概述


Swagger作为一个Api文档生成和展示工具,能够依据一套OpenApi数据规范,自动的从系统中提取的注释信息,生成动态的生成Api说明文档,OpenApi规范本身是脱胎于Swagger


Asp.Net Core中与之对应的类库分别为SwashbuckleNSwag,参考链接:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio


Swashbuckle 有三个主要组成部分:

  • Swashbuckle.AspNetCore.Swagger:将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

  • Swashbuckle.AspNetCore.SwaggerGen:从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。它通常与 Swagger 终结点中间件结合,以自动公开 Swagger JSON。

  • Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。它包括针对公共方法的内置测试工具

NSwag

NSwag 提供了下列功能:

  • 能够使用 Swagger UI 和 Swagger 生成器。

  • 灵活的代码生成功能

借助 NSwag,无需使用现有 API。也就是说,可使用包含 Swagger的第三方 API,并生成客户端实现。使用 NSwag,可以加快开发周期,并轻松适应 API更改



3


基础应用


本章主要讲解Swashbuckle的基本使用技巧


3.1 开发环境

Windows10

Vs2019

Asp.Net Core 3.1 Web API


3.2 创建项目


选择项目模板为ASP.Net Core Web API项目名称为swaggertestbase,项目依赖的框架版本为.Net Core 3.1

3.3 引用类库包


Nuget包管理页面中的浏览页签,输入swagger进行搜索,找到截图中的对应类库Swashbuckle.AspNetCore.SwaggerGenSwashbuckle.AspNetCore.SwaggerUI,选择6.0.0,选择安装按钮即可,剩余无脑确定


安装成功后,引用中目录如下:


3.4 基础配置


引入命名空间

Startup.cs中引入Swashbuckle.AspNetCore.SwaggerGen

 using Swashbuckle.AspNetCore.SwaggerGen;

注册服务

Startup.csConfigureServices服务中注册服务

 ......
 public void ConfigureServices(IServiceCollection services)
 {
     //注册服务
     services.AddSwaggerGen();
     services.AddControllers();
 }
 ......


启用静态文件中间件

由于swagger-ui需要允许客户端访问服务端静态的样式和资源,所以需要服务配置函数Configure路由中间件之前,启用静态中间件UseStaticFiles

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
 {
    .....
             //启动静态文件中间
             app.UseStaticFiles();
    .....
    //启动路由中间件
             app.UseRouting();
    .....
 }


配置Swagger中间件以及SwaggerUI中间件

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
 {
    .....
             //启动静态文件中间
             app.UseStaticFiles();
     
             #region Swagger中间件相关
             //添加swagger配置,并启动中间件
             app.UseSwagger();
             //启用Swagger-ui中间件,并配置swagger json的请求终节点
             app.UseSwaggerUI();
             #endregion
    //启动路由中间件
             app.UseRouting();
    .....
 }


启动项目

访问地址http://localhost:5000/swagger/v1/swagger.json,返回如下结果,表示默认对应Swagger Api Json结果如下:

 {
   "openapi": "3.0.1",
   "info": {
     "title": "swaggertestbase",
     "version": "1.0"
  },
   "servers": [
    {
       "url": "http://localhost:5000"
    }
  ],
   "paths": {
     "/WeatherForecast": {
       "get": {
         "tags": [
           "WeatherForecast"
        ]
      }
    }
  }
 }


访问地址http://localhost:5000/swagger/index.html,访问结果如下:


以上为默认情况下,Swashbuckle基础的相关内容。


往期推荐


点击阅读原文,更精彩~
浏览 12
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报