• .Net Core 3.x Api开发笔记 -- Swagger(七)


    Swagger 可以用来快速生成REST API文档

    其他的不多说,该章节演示如何在 .Net Core Api中使用

    在老的项目框架中使用该组件,可以参考另外一篇文章:在MVC项目中使用 Swagger API文档

    1,引用 Swashbuckle.AspNetCore 包

    2,在 Startup 中进行注册 

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "NetCore.Api", Version = "v1" });
    });

    3,在 Configure(IApplicationBuilder app, IWebHostEnvironment env) 启用中间件

    注意:下边的 v1 必须和上边的 v1相同,假如上边是 v2,下边相应的也要改成 v2

    //启用中间件服务生成Swagger作为JSON终结点
    app.UseSwagger();
    //启用中间件服务对swagger-ui,指定Swagger JSON终结点
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCore.Swagger v1");
        c.RoutePrefix = string.Empty;   //表示直接 http://localhost:5000 即可显示 Swagger UI
    });

    编辑并运行,整体效果如下:

    4,Swagger高级用法,使用Swagger为API文档增加中文说明信息

     1 //注册Swagger
     2 services.AddSwaggerGen(c =>
     3 {
     4     c.SwaggerDoc("v1", new OpenApiInfo
     5     {
     6         Title = "NetCore.Swagger",
     7         Version = "v1",
     8         Description = "一个简单的 ASP.NET Core API",
     9         Contact = new OpenApiContact
    10         {
    11             Name = "印度阿三",
    12             Email = string.Empty,
    13             Url = new Uri("https://www.cnblogs.com/peterzhang123/")
    14         }
    15     });
    16 
    17     // 为 Swagger JSON and UI设置xml文档注释路径
    18     // 获取应用程序所在目录(绝对路径,不受工作目录影响,建议采用此方法获取路径)
    19     // 此方式适用于Windows/Linux 平台
    20     var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
    21     var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml");
    22     c.IncludeXmlComments(xmlPath);
    23 
    24 });

    效果如下:

    为接口方法添加文本注释,

    1,勾选XML文档文件,文件会自动生成

    2,添加1591禁用警告显示

    对于 Linux 操作系统,会对xml文件名和路径区分大小写,可以在Starup中使用下边红框中的代码解决:

    1,给接口添加文本注释

    显示效果如下:

    2,使用 <remarks> </remarks>标签中可以使用:文本、JSON 或 XML

    显示效果如下:

    3,响应状态码  文本注释

    [ProducesResponseType(201)]
    [ProducesResponseType(400)]

    将请求参数全部删除,然后调用接口,返回结果如下:

     

    参考文档:

    https://www.cnblogs.com/yilezhu/p/9241261.html

    作者:PeterZhang
    本文版权归作者和博客园共有,欢迎转载,但必须给出原文链接,并保留此段声明,否则保留追究法律责任的权利。
  • 相关阅读:
    win7系统如何一键清理系统垃圾【系统天地】
    win7无法正常关机的解决方法【系统天地】
    win10系统开机停在请稍候解决教程【系统天地】
    Win7系统一直提示盗版怎么办【系统天地】
    windows8 flash修复怎么操作【系统天地】
    win7电脑运行速度慢如何解决【系统天地】
    Win10系统如何自动清理垃圾缓存文件【系统天地】
    Win7启用NFS服务设置的方法【系统天地】
    win7系统获得管理员取得所有权的方法【系统天地】
    Ubuntu16.04+hadoop2.7.3环境搭建
  • 原文地址:https://www.cnblogs.com/peterzhang123/p/14595049.html
Copyright © 2020-2023  润新知