zoukankan      html  css  js  c++  java
  • .net core 3.1简单swagger配置教程

    前言

    当今前后端分离开发已经成为一种大趋势,那后端开发人员给前端开发人员接口文档,无非就两种形式,手写接口文档跟在线接口文档。这时候引用swagger,让后端人员摆脱重复工作的麻烦。

    亲测有效

    开始

    1、新建项目

    随便新建个空的webapi项目

    2、引入Swagger包。

    .Net Core 中支持两个分别为Swashbuckle和NSwag。两者的配置大同小异。这里以Swashbuckle为例。

    3、配置Swagger中间件

    3.1 在Startup类ConfigureServices方法中添加Swagger服务并配置文档信息

    public void ConfigureServices(IServiceCollection services)
    {
    services.AddControllers();
    // 注册Swagger服务
    services.AddSwaggerGen(c =>
    {
    // 添加文档信息
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });
    });
    }

    3.2 在 Configure 方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

    //启用中间件服务生成Swagger作为JSON终结点
    app.UseSwagger();
    //启用中间件服务对swagger-ui,指定Swagger JSON终结点
    app.UseSwaggerUI(c =>
    {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    3.3 启动项目测试swagger是否配置成功
    输入默认端口https://localhost:5001/swagger/index.html测试,当出现如图所示,则表示成功配置。

    4、关键步骤(配置xml注释)

    4.1右击项目=》属性=》生成,修改以下配置。

     4.2 重新打开Startup类,找到AddSwaggerGen()方法中读取xml文件路径并启用

    public void ConfigureServices(IServiceCollection services)
    {
    services.AddControllers();
    // 注册Swagger服务
    services.AddSwaggerGen(c =>
    {
    // 添加文档信息
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });

    // 使用反射获取xml文件。并构造出文件的路径
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 启用xml注释. 该方法第二个参数启用控制器的注释,默认为false.
    c.IncludeXmlComments(xmlPath, true);
    });
    }

    这时候我们重新生成项目会发现项目根目录下产生一个xml文件

    测试接口的注释信息

    /// <summary>
    /// 这是一个带参数的get请求
    /// </summary>
    /// <remarks>
    /// 例子:
    /// Get api/Values/1
    /// </remarks>
    /// <param name="id">主键</param>
    /// <returns>测试字符串</returns>
    [HttpGet("{id}")]
    public string Get(int id)
    {
    return "value";
    }


    测试结果如图,我们本次的swagger配置几乎就已经大功告成了。

    注意事项

    1、以上都是本地运行测试,假如要生成发布部署到服务器,会出错,是因为默认的xml不会生成到文件夹里,需要右击更改xml文件的属性

     

     2、以目前流行的三层开发模式,一般请求跟返回实体,我们会放在model层那边,因人而异,但假如我们的Controller层引用任何一个程序集的实体,同时也想让该程序集的实体注释生成,同样也需要配置开启xml注释,如图所示

     响应实体类

    /// <summary>
    /// 返回实体
    /// </summary>
    public class SwaggerResponse
    {

    /// <summary>
    /// 编码
    /// </summary>
    public int code { get; set; }
    /// <summary>
    /// 数据
    /// </summary>
    public string data { get; set; }
    }

    控制器方法调整

    /// <summary>
    /// 这是一个带参数的get请求
    /// </summary>
    /// <remarks>
    /// 例子:
    /// Get api/Values/1
    /// </remarks>
    /// <param name="id">主键</param>
    /// <returns>测试字符串</returns>
    [HttpGet("{id}")]
    public SwaggerResponse Get(int id)
    {
    var obj = new SwaggerResponse { code = 200, data = "hello,world!" };
    return obj;
    }

    重新运行项目,如图所示则表示成功。

    ————————————————
    版权声明:本文为CSDN博主「你加班改的代码真不是我写的」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
    原文链接:https://blog.csdn.net/shaojiayong/article/details/114857949

  • 相关阅读:
    CF1137C Museums Tour(tarjan+DP)
    Educational Codeforces Round 65 (Rated for Div. 2)
    Codeforces Round #559(Div.1)
    委托
    类库
    is 和 as 运算符
    面向对象 接口
    抽象类
    面向对象 多态
    访问修饰符 程序集 静态方法
  • 原文地址:https://www.cnblogs.com/xiaohezhong/p/14647280.html
Copyright © 2011-2022 走看看