码迷,mamicode.com
首页 > Web开发 > 详细

Asp Net Core Swagger自动生成接口文档

时间:2019-03-13 19:54:30      阅读:1403      评论:0      收藏:0      [点我收藏+]

标签:agg   部分   except   nts   自动   dev   mic   ocs   call   

Swagger是什么

Swagger工具为你的Asp Net Core生成漂亮的API文档。目前社会上大部分都是一个服务端为N个客户端提供接口,往往我们需要提供一个友好的API文档,Swagger的出现,几乎使得API文档完全自动化。

开始使用Swagger

  • 此处我们使用开发IDE为VsCode,输入dotnet new webapi -o SwaggerDemo 创建ASP.NET Core Web API项目
  • 添加Swashbuckle.AspNetCore包(此处不讨论包的安装方法,请自行上网搜索),在.csproj文件中会生成如下引用
    技术图片
  • 打开Startup.cs文件,添加如下代
        public Startup(IConfiguration configuration, IHostingEnvironment env)
        {
            Configuration = configuration;
            this.Env = env;
        }
        public IHostingEnvironment Env { get; }

        public IConfiguration Configuration { get; }

        public string[] docs = new[] { "未分类" };

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            if (Env.IsDevelopment())
            {
                services.AddSwaggerGen(options =>
                {
                    foreach (var d in docs) options.SwaggerDoc(d, new Info { Version = d });
                    options.DocInclusionPredicate((docName, description) =>
                    {
                        description.TryGetMethodInfo(out MethodInfo mi);
                        var attr = mi.DeclaringType.GetCustomAttribute<ApiExplorerSettingsAttribute>();
                        if (attr != null)
                        {
                            return attr.GroupName == docName;
                        }
                        else
                        {
                            return docName == "未分类";
                        }
                    });
                    var ss = options.SwaggerGeneratorOptions;
                    options.IncludeXmlComments(@"E:\VsCode\C#\.Net Core\第三章 利用Swagger生成接口文档\SwaggerDemo\bin\Debug\netcoreapp2.2\SwaggerDemo.xml");
                });
            }
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            app.UseMvc();
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwagger()
                .UseSwaggerUI(options  =>
                {
                    options.DocumentTitle = "Ron.liang Swagger 测试文档";
                    foreach (var item in docs)
                        options.SwaggerEndpoint($"/swagger/{item}/swagger.json", item);
                });
            }
        }

代码中涉及到的xml需要换成自己的路径

技术图片

 为保证自己项目xml文档的生成 把.csproj文件添加以下属性

技术图片

doenet build--->dotnet run-->访问https://localhost:8090/swagger/index.html(此处需要换成自己的网站地址)可以看到api文档已经成功生成,赶快自己点击玩玩把~~~

技术图片

添加分组和注释信息

上面我们用的默认API文档,实际工作中我们需要分类以及注释信息等。下面我们添加一个测试分组

  • 首先打开我们的api控制器(ValuesController).修改为

技术图片

  • 添加注释信息

技术图片

再次访问

技术图片

 

 总结

  • 利用Swagger自动生成API文档
  • 对每个控制器进行分组
  • 自动抓取注释内容
  • 在API文档界面进行测试

 

 

Asp Net Core Swagger自动生成接口文档

标签:agg   部分   except   nts   自动   dev   mic   ocs   call   

原文地址:https://www.cnblogs.com/FashionDoo/p/10525448.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!