Блог

https://github.com/domaindrivendev/Swashbuckle .AspNetCore

По умолчанию Swagger JSON будет отображаться на следующем маршруте — «/swagger/{DocumentName}/swagger.json». При необходимости вы можете изменить это при включении промежуточного программного обеспечения Swagger. Пользовательские маршруты ДОЛЖНЫ включать параметр {DocumentName} .

Почему конфигурация шаблона требует этого заполнителя, а конфигурация пользовательского интерфейса — нет?

 app.UseSwagger(c =>
{
    c.RouteTemplate = "api-docs/{documentName}/swagger.json";
})
NOTE: If you're using the SwaggerUI middleware, you'll also need to update its configuration to reflect the new endpoints:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
})
  

{documentName} Для чего? Есть ли функция для динамической замены или что-то в этом роде? Потому что конфигурация пользовательского интерфейса в примере настроена статически. почему это не должно быть просто "/api-docs/v1/swagger.json" в конфигурации RouteTemplate?

DocumentName

{documentName} Относится к имени, которое вы указываете в AddSwaggerGen() методе.

Следующий код используется myapi в качестве имени для документа swagger .

 builder.Services.AddSwaggerGen(options =>
  options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" })
);
  

Используя UseSwagger следующим образом

 app.UseSwagger(options =>
  options.RouteTemplate = "swagger/{documentName}/swagger.json");
  

приводит к созданию файла swagger в следующем расположении:
/swagger/myapi/swagger.json

Это означает, что ваша конфигурация пользовательского интерфейса Swagger должна быть

 app.UseSwaggerUI(options => {
  options.SwaggerEndpoint("/swagger/myapi/swagger.json", "Swagger v1");
});
  

Пользовательский интерфейс Swagger может создавать пользовательский интерфейс на основе любого файла swagger, независимо от того, получен он из этого проекта или нет. Вот почему он не включает {documentName} заполнитель. Между ними не обязательно существует взаимосвязь.

Несколько пользовательских интерфейсов Swagger

Это, например, конфигурация, в которой у меня есть 1 документ Swagger, 2 файла swagger и две конечные точки пользовательского интерфейса. Я описываю тот же API, но один раз с использованием стандарта OpenAPI v3 и один раз с использованием старого стандарта Swagger v2.

 builder.Services.AddSwaggerGen(options =>
{
  options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" });
});

app.UseSwagger(options =>
{
  options.SerializeAsV2 = true;
  options.RouteTemplate = "swagger/{documentName}/swaggerV2.json";
});

app.UseSwagger(options =>
{
  options.SerializeAsV2 = false;
  options.RouteTemplate = "swagger/{documentName}/openapiV3.json";
});

app.UseSwaggerUI(options => {
  options.SwaggerEndpoint("/swagger/myapi/openapiV3.json", "OpenApi v3");
  options.SwaggerEndpoint("/swagger/myapi/swaggerV2.json", "Swagger v2");
});
  

Когда вы перейдете в пользовательский интерфейс swagger, вы увидите выпадающий список для выбора одной из двух конечных точек.

Несколько документов Swagger

Ваше приложение также может иметь несколько документов swagger. Например, ваш «обычный» API некоторые устаревшие API.

 options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" });
  options.SwaggerDoc("myapiLegacy", new OpenApiInfo { Title = "My Legacy API", Version = "v1" });
  

Существует несколько способов указать, когда метод вашего проекта принадлежит определенному документу swagger. Но самый простой способ — пометить его атрибутом:

 [HttpPost]
[ApiExplorerSettings(GroupName = "myapiLegacy")]
public void Post([Product product)
  

Итак, поскольку у вас может быть несколько документов swagger, имеет смысл создать для него заполнитель. т. е. {documentName} .

В моем пользовательском интерфейсе swagger я теперь получаю 4 конечных точки:

• обычный api как Swagger V2
• обычный api как OpenAPI V3
• устаревший api как Swagger V2
• устаревший api как OpenAPI V3