在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
            services.AddSwaggerDocument();
        }

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

        if (env.IsDevelopment())
        {


             // 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();


        }

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

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

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


             app.UseSwaggerUI(options =>
             {
                 options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
                 options.RoutePrefix = string.Empty;
             });

        }

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

注意：

Swagger（OpenApi）

相关

标签