Asp.Netcore 使用swagger 来自动生成API文档

一. 安装nuget包

      搜索并安装：Swashbuckle.AspNetCore的包

      结果如图所示：

      

二.开始使用

    1.在Startup文件的 ConfigureSevers 里面添加如下代码：

        services.AddSwaggerGen(options =>
            {

                options.DocInclusionPredicate((docName, description) => true);//这两句是支持动态Api的文档
                options.CustomSchemaIds(type => type.FullName);//这两句是支持动态Api的文档
                options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取代码运行的相对路径
                options.IncludeXmlComments(Path.Combine(basePath, "Api.xml"), true);//插入代码上的注释放入Swagger
            });

        这里需要添加

               using Swashbuckle.AspNetCore.Swagger;

     2.在Startup文件的Configure 里面添加如下代码：

           app.UseSwagger();
            app.UseSwaggerUI(option =>
            {
                option.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

三.启动项目即可使用。

     默认路由：https://localhost:【端口号】/swagger

    如下图所示：

注意事项：

所有Controller和方法必须要有 Route ，也可以简写 [HttpGet("test")].如下图所示

如果不写会出现错误：  Not Found /swagger/v1/swagger.json   如下图所示

四.显示c#代码的注释

     1.打开用户属性 选到生成栏，如下图所示，添加取消警告码：1591，设置xml文档文件存储路径

2.配置启动Swagger时使用xml文档，如下图所示

3.这样swagger上就会显示c#代码里面写的注释，如下图所示：

   注：如果需要显示类的注释时，如下修改注入文档的方法

     如下：

         

4.注释标准写法 如下所示

        /// <summary>
        /// 封装后的linq的查询方式
        /// </summary>
        /// <typeparam name="T">要查询和返回的Json</typeparam>
        /// <param name="indexName">index的名称</param>
        /// <param name="typeName">type的名称</param>
        /// <param name="selector">linq内容</param>
        /// <response code="200">返回值时泛型的List</response>
        public async Task<List<T>> SearchAsync<T>(string indexName, string typeName, Func<QueryContainerDescriptor<T>, QueryContainer> selector = null) where T : class
        {
            var list = await ElasticLinqClient.SearchAsync<T>(option => option.Index(indexName.ToLower()).Type(typeName).Query(selector));
            return list.Documents.ToList();
        }