• Asp.Net Core SwaggerUI 接入


    Asp.Net Core SwaggerUI 接入

    简单了解

    swagger的目的简单来说就是,不用为每个接口手动写接口文档,因为它是根据接口自动生成的,接口更改时文档也同步更新,减少了手动更新的麻烦和遗漏。同时也提供了接口的调试等功能,你不用打开postman等接口测试软件来测试接口;如果有写备注的话,接口、入参和输出都有详细的备注说明,调用接口的人也能更加直观的读懂接口。沟通效率和工作效率也会大大提升。

    Swagger接入的步骤:

    1. 注册Swagger生成器:services.AddSwaggerGen().
    2. 插入中间件,将生成的Swagger公开为JSON节点:app.UseSwagger()
    3. 插入Swagger-UI中间件,将指定的swagger json端点为其提供支持:app.UseSwaggerUI()

    一、添加Nuget包

    Package Manager : Install-Package Swashbuckle.AspNetCore
    或
    CLI : dotnet add package Swashbuckle.AspNetCore
    

    二、注册swagger文档服务

    • 注意

    1. 如果mvc使用的是services.AddMvcCore(),则需要手动添加ApiExplorer,因为SwashBuckle强烈依赖于ApiExplorer,ApiExplorer用来发现控制器中的接口方法。需要手动添加。如:
      services.AddMvcCore().AddApiExplorer();

    2. 如果使用的是services.AddMvc(),则不需要再进行注册。因为AddMvc()中已经添加了ApiExplorer。如:

          public static IMvcBuilder AddMvc(this IServiceCollection services)
          {
              if (services == null)
                  throw new ArgumentNullException(nameof (services));
              IMvcCoreBuilder builder = services.AddMvcCore();
              builder.AddApiExplorer();//在这里
              builder.AddAuthorization();
              MvcServiceCollectionExtensions.AddDefaultFrameworkParts(builder.PartManager);
              builder.AddFormatterMappings();
              builder.AddViews();
              builder.AddRazorViewEngine();
              builder.AddRazorPages();
              builder.AddCacheTagHelper();
              builder.AddDataAnnotations();
              builder.AddJsonFormatters();
              builder.AddCors();
              return (IMvcBuilder) new MvcBuilder(builder.Services, builder.PartManager);
          }
      
    3. 什么时候用AddMvc(),什么时候用AddMvcCore()呢?
      通过AddMvc()的方法中我们应该可以发现,里面有添加ViewRazorTagHelper服务,这些在WebApi项目中是用不到的。所以:
      1).如果你的项目是mvc web程序,则使用AddMvc().
      2).如果的项目是webapi,则使用AddMvcCore(),然后酌情添加需要的其它服务;当然使用AddMvc()也没有问题。

    • 添加Swagger服务

    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc(AppDefaults.ApiDocumentName, new Info
        {
            Title = AppDefaults.ApiDocumentTitle,
            Description = AppDefaults.ApiDocumentDescription,
            Version = typeof(Startup).Assembly.GetName().Version.ToString()
        });
        //加载注释文件
        Directory.GetFiles(Environment.ContentRootPath, "*.xml", SearchOption.AllDirectories)
            .ToList()
            .ForEach(f => options.IncludeXmlComments(f));
    });
    

    三、添加管道

    //生成swagger-json文件,并重定义swagger-json文件路由模板,这里我修改了 swagger-json 的路由模板。
    //如果不自定义的话,默认是 swagger/{documentName}/swagger.json
    app.UseSwagger(options => options.RouteTemplate = "{documentName}/swagger.json");
    
    app.UseSwaggerUI(options =>
    {
        //指定生成swagger-json文件路径,为SwaggerUI提供数据。
        //如果上边路由模板没有自定义,则完成路径是 /swagger/{AppDefaults.ApiDocumentName}/swagger.json
        options.SwaggerEndpoint($"/{AppDefaults.ApiDocumentName}/swagger.json", AppDefaults.ApiDocumentName);
    
        //自定义SwaggerUI页面路由前缀
        //地址栏输入 http://loacalhost:5000/lxp  就可以打开SwaggerUI页面
        options.RoutePrefix = "lxp";
    });
    

    四、定义接口

    • 如果想要控制器在Swagger中显示,所有控制器必须使用属性路由
    • 接口方法要使用 Http 属性和 From 特性标注

    例如:

        [Route("[controller]")]
        [ApiController]
        public class ValuesController : ControllerBase
        {
            [HttpGet("name")]
            public async Task<ActionResult<string>> GetNameAsync([FromQuery] string name)
            {
                if (!string.IsNullOrEmpty(name))
                {
                    ModelState.TryAddModelError(nameof(name), $"{nameof(name)} can not be empty");
                }
    
                if (!ModelState.IsValid)
                {
                    return BadRequest(ModelState);
                }
    
                return await Task.FromResult(name);
            }
        }
    

    补充:

    • AppDefaults 是我定义一个常量的类

  • 相关阅读:
    ASP.NET MVC4 Web 编程第三章
    ASP.NET MVC4 Web 编程第二章
    2020.08.25日
    ASP.NET MVC4 Web 编程第一章
    .net你必须知道的事儿 2.2
    .net你必须知道的事儿 2.1
    资本论
    Cent os mysql主从同步问题
    apache启动脚本
    zentao(禅道)迁移
  • 原文地址:https://www.cnblogs.com/imlxp/p/11223952.html
Copyright © 2020-2023  润新知