1

我正在使用带有Redoc的 Swashbuckle来记录我的 ASP.NET Core 2.2 API。现场 ReDoc 演示在顶部有一组部分（例如“介绍”），其中包含一些自定义 html。我想在我的 API 中生成类似的部分，但不知道该怎么做。

基本上我有：

services.AddSwaggerGen(c => {
    c.SwaggerDoc(...);
    c.IncludeXmlComments(...);
    c.AddSecurityDefinition("OAuth2", ...);
});

然后：

app.UseReDoc(c => {
    c.SpecUrl = "/swagger/v1/swagger.json";
    c.RoutePrefix = "";
});

我已经浏览了 intellisense 选项，以及 Swashbuckle自述文件和wiki，但找不到生成此类部分的方法。

将 HTML 部分添加到基于 Swashbuckle.AspNetCore.ReDoc 的文档开头的方法是什么？

4

1 回答 1

3

您可以在传递给的Description中使用降价。您可以在 ReDoc 中包含最终作为侧边栏导航项的标题。例如：InfoSwaggerDoc(...)

c.SwaggerDoc(Version, new Info
    {
        Title = "My API",
        Description = @"This is our API.

            ## Introduction

            We can use markdown (with [links](https://example.org)) to explain more about the API.

            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

            - Bullet item
            - And another bullet item

            Some more lorem ipsum.

            ## Logging

            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

            Here's a sample block:

            ```bash
            curl https://example.org/api/v1/some-method \
            -H 'X-Header: value' \
            -v
            ```

            Lorem ipsum **doler sit met something more** test text.
        ",
});

我建议将该 markdown 放在嵌入式资源文件（例如api-intro.md）中并在运行时读取它。

于 2019-01-22T09:52:28.347 回答