C#(.Net Core WebAPI)之API文档的生成(Swagger)

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了C#(.Net Core WebAPI)之API文档的生成(Swagger)相关的知识,希望对你有一定的参考价值。

一 : 安装Swagger

Swashbuckle.AspNetCore
在NuGet 中,安装 Swashbuckle.AspNetCore :
技术图片
我使用的版本为 : 5.0.0-rc2

二 : 引入Swagger功能

Ⅰ : Startup.cs
① ,ConfigureServices方法中:

public void ConfigureServices(IServiceCollection services)
        
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2).AddJsonOptions(options =>
            
                options.SerializerSettings.Formatting = Formatting.Indented;
            );
            services.AddSwaggerGen(options =>
            
                options.SwaggerDoc("v1", new OpenApiInfo()
                
                    Title = "Swagger Test UI",
                    Version = "v1",
                    Description = "Aonaufly first ASP.NET Core Web API"
                );
                options.CustomSchemaIds(type => type.FullName); // 解决相同类名会报错的问题
                options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "WebAPIPoco.xml")); // 标注要使用的 XML 文档
                options.DescribeAllEnumsAsStrings();
            );
        

②:Configure中

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        
            if (env.IsDevelopment())
            
                app.UseDeveloperExceptionPage();
            
            else
            
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            
            //设置全局跨域
            app.UseCors(builder => builder.AllowAnyOrigin());
            app.UseHttpsRedirection();
            app.UseSwagger(c =>  c.RouteTemplate = "swagger/documentName/swagger.json"; );
            // 在这里面可以注入
            app.UseSwaggerUI(options =>
            
                options.ShowExtensions();
                options.ValidatorUrl(null);
                options.SwaggerEndpoint("/swagger/v1/swagger.json", "Aonaufly API V1");
                options.DocExpansion(DocExpansion.None);
            );
            app.UseMvc();
        

三 :配置设置

①,到处项目XML , 加入1591禁止警告
技术图片
②,将项目XML生成路径复制到项目根路径
copy $(TargetDir)WebAPIPoco.xml $(ProjectDir)WebAPIPoco.xml
技术图片
③,重置默认网页为swagger , 默认是 api/values
技术图片

四 :初始结果

技术图片

五 : 测试

/// <summary>
        /// 带参数的get请求
        /// </summary>
        /// <remarks>
        /// <code>
        /// 输入 : int
        /// 输出 : string
        /// </code>
        /// </remarks>
        /// <param name="id">ID号</param>
        /// <returns>String</returns> 
        /// <response code="201">返回字符串</response>
        /// <response code="400">如果id为空</response>
        // GET api/values/5
        [HttpGet("id")]
        [ProducesResponseType(201)]
        [ProducesResponseType(400)]
        public ActionResult<string> Get(int id)
        
            return "value";
        

结果:
技术图片

以上是关于C#(.Net Core WebAPI)之API文档的生成(Swagger)的主要内容,如果未能解决你的问题,请参考以下文章

C# 和 Docker - 无法从容器化 .NET Core 3.1 Web API 连接到容器化 MySQL 服务器

API不接受对象列表作为参数.Net Core webAPI

[Asp.Net Core]ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

使用 ASP.NET Core MVC 创建 Web API

.NET Core 2 Web API:CORS 问题

使用 ASP.NET Core MVC 创建 Web API