在ASP.NET Core web API使用Swagger/OpenAPI(二)

时间:2021-11-25
本文章向大家介绍在ASP.NET Core web API使用Swagger/OpenAPI(二),主要包括在ASP.NET Core web API使用Swagger/OpenAPI(二)使用实例、应用技巧、基本知识点总结和需要注意事项,具有一定的参考价值,需要的朋友可以参考一下。

实战

首先介绍三个重要组件:

  • Swashbuckle.AspNetCore.Swagger:一个把SwaggerDocument对象暴露成JSON端点(openapi.json对应的URI)的Swagger对象模型和中间件。
  • Swashbuckle.AspNetCore.SwaggerGen:一个根据Routes(路由),Controllers(控制器),Models(模型对象)生成SwaggerDocument的生成器,它通常与Swagger端点中间件相结合,自动公开Swagger JSON(openapi.json)。
  • Swashbuckle.AspNetCore.SwaggerUI:根据openapi.json生成的对应的UI界面

一、安装包

方式一:在与项目文件夹相同的目录下执行如下代码:

Install-Package Swashbuckle.AspNetCore -Version 6.2.3

方式二:使用Nuget包管理工具:

添加并配置Swagger中间件

Program.cs文件中把Swagger生成器添加到服务集合

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            // Register the Swagger services
            <span style="backgroundColo:yellow">services.AddSwaggerDocument();</span>
        }

也在Program.cs启用生成JSON文档和SwaggerUI的中间件

        if (env.IsDevelopment())
        {
<div style="backgroundColo:yellow">
             // Enable middleware to serve generated Swagger as a JSON endpoint.
             app.UseSwagger();
             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
             // specifying the Swagger JSON endpoint.
             app.UseSwaggerUI();
</div>
        }

上面添加的两行代码只有在开发环境时才会生效,如果想在生产环境也使用Swagger,就别放在上面的if判断内

运行程序并访问https://localhost:<port>/swagger/v1/swagger.json就能看到openapi.json文档了。port为自己电脑对应的端口比如(默认5000或5001)

通过https://localhost:<port>/swagger路径访问SwaggerUI
如果想把SwaggerUI的路径设置成根路径(https://localhost:/),把对应的RoutePrefix属性设为空字符串就行了


             app.UseSwaggerUI(options =>
             {
                 options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
<div style="backgroundColo:yellow">
                 options.RoutePrefix = string.Empty;
</div>
             });

        }

如果使用了IIS或者反向代理,用过添加./前缀来Swagger端点使用相对地址,例如 ./swagger/v1/swagger.json,/swagger/v1/swagger.json表示程序在URL的真实跟目录下寻找JSON文件,比如使用https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json而不是https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json

注意:

原文地址:https://www.cnblogs.com/michaelshen/p/15603960.html