.net core 3.0_webapi项目使用Swagger提供接口帮助页面

　　前言：我们开发了很多的接口后，为了方便调用人员使用，需要给出接口地址，参数和解释说明，可能还需要示例。? 那么swagger这个开源项目，已经给我们提供好了一整套的解决方案：

　　本博客参考文档：

　　Swashbuckle 和 ASP.NET Core 入门??

　　什么是 Swagger/OpenAPI？

Swagger 是一个与语言无关的规范，用于描述?REST?API。?Swagger 项目已捐赠给?OpenAPI 计划，现在它被称为开放 API。?这两个名称可互换使用，但 OpenAPI 是首选。?它允许计算机和人员了解服务的功能，而无需直接访问实现（源代码、网络访问、文档）。?其中一个目标是尽量减少连接取消关联的服务所需的工作量。?另一个目标是减少准确记录服务所需的时间。（说明参考微软官方文档：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.0）

?

　　快速添加webapi项目对swagger的支持：

　　1-添加程序包引用：Swashbuckle.AspNetCore -Version 5.0.0-rc4? ?(该版本目前属于预览版，需要勾选预览版才可以看到)

　? 2-添加并配置 Swagger 中间件：

using Microsoft.OpenApi.Models;


public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger generator,defining 1 or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1",new OpenApiInfo { Title = My API" });

                 include document file
                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory,${typeof(Startup).Assembly.GetName().Name}.xml"),1)">true);
            });

    services.AddControllers();
}

　　这里，需要添加对项目xml文件的引用，默认启用根目录下的项目文件名的xml文件，项目xml文件生成配置如下：

　　为了兼容发布版本，咱们设置了输出路径为空，xml名称改为：项目名.xml??

?

?

?

　　3-在?Startup.Configure?方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

 Configure(IApplicationBuilder app)
{
     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(c =>
    {
        c.SwaggerEndpoint(/swagger/v1/swagger.jsonMy API V1");
    });

    app.UseStaticFiles();
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

?

　　4-结束，查看效果：

　　启动应用，并导航到：?http://localhost:<port>/swagger/v1/swagger.json。?生成的描述终结点的文档显示在?Swagger 规范 (swagger.json)?中。

　　可在?http://localhost:<port>/swagger? 找到 Swagger UI。?通过 Swagger UI 浏览 API

?

?

?

?

　　5-走过的坑1：官网文档前半部分并没有让添加xml文件的代码。后面有涉及，不过还是感觉有点乱，本博客已加上！

　　走过的坑2：常见异常：Ambiguous HTTP method for action - PaymentAccountAPI.Controllers.PayAccountController.GetTransactions (PaymentAccountAPI). Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0

　　该异常是因为控制器方法，缺少方法类型的标记，[HttpGet]、[HttpPost],如下图：

　　参考解决方案文档：Ambiguous HTTP method Actions require an explicit HttpMethod binding for Swagger 2.0

?

?

?　　走过的坑3：缺少xml项目文件异常_500错误：? ? 项目部署到IIS后，不会自动把xml文件带过去，需要我们收到复制过去，在运行查看效果。

?

?

　　?把项目xml文件放入后，再试（需要重启IIS项目），效果正常：

?

?

?

?

?

?

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!