标签: swagger-ui

例如我有 2 个 API 操作：

获取 v1/people/{id}

发布 v1/people/{id}

我的 Swagger UI API 文档中仅显示了这些操作之一，但我希望同时显示这两个操作。我有很多这样的例子。Swagger 文档中指出：

“ Swagger 将独特的操作定义为路径和 HTTP 方法的组合。 ”

这会让我觉得我想做的事情是可能的，因为它们是由 HTTP 方法唯一标识的。

如果我更改 swagger.yaml 文件中的一个路径参数，它们都会显示。例如：

获取 v1/people/{personid}

发布 v1/people/{id}

但我宁愿保持它们都是标准的，否则我的 API 文档会显得混乱。

我正在使用 swagger-ui-express 4.1.4。

/v1/people/{id}:
get:
  summary: Get people.
  security:
    - cookieAuth: []
  tags:
    - People
  parameters:
    - in: path
      name: id
      required: true
      schema:
        type : integer
        example: 123
  responses: 
    '200':
      description: OK



/v1/people/{id}:
    post:
      summary: Get people.
      security:
        - cookieAuth: []
      tags:
        - People
      parameters: …

我有一个 ASP.NET Core 3.1 API 端点，配置如下：

[HttpGet("api/controller/action/{id}")]
public async Task<IActionResult> GetSingle([FromRoute] GetSingleRequest request) {...}

DTO 有一个 Guid 属性：

public class GetSingleRequest
{
  public Guid Id { get; set; }
}

我已经配置了一个自定义模型绑定器来将 Guid 属性绑定到字符串值，因为我使用的是短 guid 实现。使用 Postman 进行测试时一切正常。

但是，使用Swagger时，不是传递输入的路由参数，而是传递参数模板，例如

GET /api/controller/action/{id}     // Literally constructs the URI with {id}
GET /api/controller/action/abcd1234 // Not the value as entered

我尝试过使用MapTypeandISchemaFilter如下：

// startup.cs
c.MapType<Guid>(() => new OpenApiSchema {Type = "string", Format = null});

// startup.cs
c.SchemaFilter<GuidSchemaFilter>();

// GuidSchemaFilter.cs
internal class GuidSchemaFilter …

我有一个 Spring Boot 应用程序，它从 2 个规范文件生成 2 个 API。我可以swagger-ui通过添加为其中之一生成一个页面

springdoc.swagger-ui.url=/firstAPI.yaml

到application.properties。但是我怎样才能包含第二个 API 呢？

我试过：

springdoc.swagger-ui.urls=/firstAPI.yaml,/secondAPI.yaml

这会创建一个组合http://localhost:8080/v3/api-docs/，但http://localhost:8080/v3/api-docs/尽管可以在顶部栏中的两个规格之间进行选择，但页面显示“无法加载 API 定义”。

所以我知道我可以使用 quarkus.smallrye-openapi.path=/openapi 更改开放 api 路径

不过，我使用的是 api 网关，在服务开始时，我使用 https://gateurl/notification/swagger-ui/ 之类的内容来标识它们

如何更改 open api 的 url，这样我就不必在每次打开 url 时手动将 /notification/openapi 放入 swagger 中

当以下 POCO 类的“Salary”字段的十进制值为 12000M（十进制值）时，Swagger UI 将 JSON 属性值显示为 12000。而预期的 JSON 属性值为 12000.0（即尾随零）。

在startup.cs的“ConfigureServices(IServiceCollection services)”方法中使用以下代码：

services.AddControllers().AddNewtonsoftJson(options =>
{
    options.SerializerSettings.FloatParseHandling = FloatParseHandling.Decimal;
    options.SerializerSettings.FloatFormatHandling = FloatFormatHandling.DefaultValue;
});
services.AddControllersWithViews().AddNewtonsoftJson(options =>
{
    options.SerializerSettings.FloatParseHandling = FloatParseHandling.Decimal;
    options.SerializerSettings.FloatFormatHandling = FloatFormatHandling.DefaultValue;
});

还使用了以下代码片段，但 Swagger UI 中没有出现预期的输出。（在 Swashbuckle.AspNetCore.Newtonsoft V6.1.4.0 中）

services.AddAwaggerGenNewtonsoftSupport();

当上面的代码片段不起作用时，也尝试以下。但没有运气。

services.AddMvc().AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.FloatParseHandling = FloatParseHandling.Decimal;
        options.SerializerSettings.FloatFormatHandling = FloatFormatHandling.DefaultValue;
    });

班级：

public class Employee{
   public string EmployeeName {get; set;}
   public decimal Salary {get; set;}
   public string Department {get; set;}
}

看起来，即使添加上述代码片段后，Swagger UI 也没有使用 Newtonsoft.Json 来序列化十进制，而是使用 …

我正在使用 NestJs。我有这个控制器：

@Get(':id')
  @ApiOperation({ summary: 'Get action by id' }) 
  findById(@Param('id') id: string, @Query() query?: SelectQuery & PopulateQuery): Promise<Action> {
    return this.actionService.findById(id, query);
  }

当我在 Swagger 中打开页面时，它说没有可用的参数。

在Swagger中，如何将参数“id”作为输入框，以便我可以在Swagger（浏览器）中使用它？

谢谢。

本质上，当我创建项目并创建一个功能 API（用户可以在其中创建、删除数据库中的信息等）并运行它时，我得到了可用于测试该 API 的 swagger UI。

现在我知道它有效了，我想开始在网站上实际构建页面，而不是大摇大摆。然而，即使当我尝试将 web.config 文件中的默认页面设置为我的 Index.cshtml 时，它也会变得大摇大摆。

基本上我的问题是，我该如何改变这个？

我想将图像添加到 FastAPI 自动文档（由 Swagger UI 提供），但我不知道如何执行此操作。这是代码：

@api.get(path='/carbon-credit/',
    responses={
        200: {'description': 'Ok',
            "content": {
            "image/jpeg": {
                "example": 'https://picsum.photos/seed/picsum/200/300'
                    }
                }},
        404: {"description": "not found"},
        422: {'description': 'not found 2'},
    },
    name='API for Carbon Credit',
    description="get carbon credit",
    tags=['Images'],
    response_class=Response)

正如您从代码中看到的，我尝试使用 URL 来执行此操作，而我在 ReDoc 和 Swagger UI 中得到的只是文本形式的 URL，而不是实际图像。另外，我想使用存储在本地驱动器中的图像。

Swagger UI 和 ReDoc 的屏幕截图：

我怎样才能做到这一点？

提前致谢。

Nestjs swagger ui 在部署到 vercel 时不加载样式，但在本地运行良好

控制台和网络请求

我使用以下配置添加了 vercel.json 并部署到 vercel。

{
  "version": 2,
  "builds": [
    {
      "src": "src/main.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/main.ts",
      "methods": ["GET", "POST", "PUT", "PATCH", "DELETE"]
    }
  ]
}

主要.ts

const swaggerConfig = new DocumentBuilder()
  .setTitle('Tansfun')
  .setDescription('API for Tansfun')
  .setVersion('1.0')

  .addBearerAuth(
    {
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'APIKey',
      name: 'APIKey',
      description: 'Enter API Key',
      in: 'header',
    },
    'APIKey-auth', 
  )
  .build();

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const …

当我使用 swashbuckle 运行 .NET Core 服务时，它显示的标题（在所有资源之上）源自程序集名称。

如何指定我自己的标题出现在 swagger 页面上？

（页面上显示的标题与文档标题不同，可以通过options.DocumentTitle传入app.UseSwaggerUI()方法进行修改。）

编辑：这是我当前的设置代码 - 这是 C# 模板开箱即用的代码webapi：

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();