Swagger 文档的路径为空答案

【问题标题】：Swagger doc has empty pathsSwagger 文档的路径为空
【发布时间】：2021-01-14 15:14:52
【问题描述】：

我的 Swagger 文档未正确生成，我有基本信息（头衔、姓名、许可证等），但我的路线上没有文档。

这是 Startup.cs 中的设置：

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<APIContext>(options => options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
        services.AddControllersWithViews();
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo
            {
                Version = "v1",
                Title = "OpenWeb Challenge",
                Description = "A 'simple' example ASP.NET Core Web API",
                TermsOfService = new Uri("https://example.com/terms"),
                Contact = new OpenApiContact
                {
                    Name = "Anthony Da Silva Ferreira",
                    Email = string.Empty,
                    Url = new Uri("https://twitter.com/spboyer"),
                }
            });

            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "OpenWebChallenge V1");
        });
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(name: "default",pattern: "{controller=Home}/{action=Index}/{id?}");
        });
    }

还有招摇的内容：

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenWeb Challenge",
    "description": "A 'simple' example ASP.NET Core Web API",
    "termsOfService": "https://example.com/terms",
    "contact": {
      "name": "Anthony Da Silva Ferreira",
      "url": "https://twitter.com/spboyer",
      "email": ""
    },
    "license": {
      "name": "Licence",
      "url": "https://example.com/license"
    },
    "version": "v1"
  },
  "paths": { },
  "components": { }
}

控制器示例：

public class ContactsController : Controller
{
    private readonly APIContext _context;

    public ContactsController(APIContext context)
    {
        _context = context;
    }

    // GET: Contacts
    public async Task<IActionResult> Index()
    {
        return View(await _context.Contacts.ToListAsync());
    }

    // GET: Contacts/Details/5
    public async Task<IActionResult> Details(int? id)
    {
        if (id == null)
        {
            return NotFound();
        }

        var contact = await _context.Contacts
            .Include(c => c.ContactSkills)
                .ThenInclude(cs => cs.Skill)
            .AsNoTracking()
            .FirstOrDefaultAsync(m => m.Id == id);

        if (contact == null)
        {
            return NotFound();
        }

        return View(contact);
    }
}

我是否缺少任何配置或其他内容？这是我第一次从头开始创建 API。

【问题讨论】：

标签： asp.net-core swagger swashbuckle.aspnetcore

【解决方案1】：

您是否已将 PropertyGroup 添加到 PROJECT_NAME.csproj 文件中？

<PropertyGroup>
   <GenerateDocumentationFile>true</GenerateDocumentationFile>
   <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

没有它，编译器将不会生成文档文件。

Microsoft Documentation

编辑

在文档中它说：“您必须为要在 Swagger 文档中表示的任何控制器使用属性路由”Link。因此，对于您的控制器，它将是：

[Route("api/contacts")]
public class ContactsController : Controller
{
...

    // GET: Contacts
    [HttpGet("")]
    public async Task<IActionResult> Index()
    {
    ...
    }

    // GET: Contacts/Details/5
    [HttpGet("/details/{id?}")]
    public async Task<IActionResult> Details([FromRoute] int? id)
    {
        ...
    }
}

编辑

我使用了错误的路由模板语法：

[HttpGet("/details/:id?")] -> [HttpGet("/details/{id?}")]

？可选参数

【讨论】：

是的，GenerateDocumentationFile 属性在那里，我没有放 NoWarn，它是强制性的吗？
如果没有 NoWarn，您将收到有关缺少 XML cmets 的警告，但这不是强制性的。你能分享一个你的控制器吗？
它给出了这个错误：RoutePatternException: The literal section ':id?'是无效的。文字部分不能包含“？”字符。
也试过：{id}，运行时没有错误，但在 swagger.json 生成时有错误。
对不起，我的错误，asp.net核心中的模板语法是“/details/{id?}”。这？用于可选路由参数。我使用 react-router 的模板语法 :) sry.

【解决方案2】：

从您的代码来看，ContactsController 看起来像一个 MVC 控制器（它将返回视图），而不是 API 控制器。

The Swagger (OpenAPI) 是一种与语言无关的规范，用于描述 REST API，而不是 MVC 控制器。因此，它不会为 MVC 控制器生成 Swagger 文档。尝试添加 API 控制器，然后使用 Swagger 添加 API 信息和描述。

更多关于使用 Swagger 的详细信息，请查看Get started with Swashbuckle and ASP.NET Core

【讨论】：