В Swagger @Api
аннотация description
устарела.
Есть ли новый способ предоставления описания?
В Swagger @Api
аннотация description
устарела.
Есть ли новый способ предоставления описания?
Я нашел решение для моего приложения загрузки Spring. Во-первых, используйте метод tags
для определения определений тегов в Docket
:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket productApi() {
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("my.package")).build()
.apiInfo(apiInfo())
.tags(new Tag("tag1", "Tag 1 description."),
new Tag("tag2", "Tag 2 description."),
new Tag("tag2", "Tag 3 description."));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("My API").version("1.0.0").build();
}
}
После того, как в RestController
просто добавьте аннотацию @Api
одним (или более) тегами. Например:
@Api(tags = { "tag1" })
@RestController
@RequestMapping("tag1Domain")
public class Tag1RestController { ... }
Это правильный способ добавить описание в документацию Swagger API для v1.5:
@Api(tags = {"Swagger Resource"})
@SwaggerDefinition(tags = {
@Tag(name = "Swagger Resource", description = "Write description here")
})
public class ... {
}
Причина, по которой она устарела, заключается в том, что предыдущие версии Swagger (1.x) использовали аннотацию описания @Api
для групповых операций.
В спецификации Swagger 2.0 было создано понятие tags
и создано более гибкий механизм группировки. Чтобы соответствовать API, поле description
было сохранено, поэтому обновление было бы простым, но правильный способ добавления описания - это атрибут tags
, который должен ссылаться на аннотацию @Tag
. @Tag
позволяет вам предоставить описание, а также внешние ссылки и т.д.
Я тоже задавался вопросом, что делать с использованием устаревшего description
(отображаемого как предупреждения в моей IDE).
Что ж, при ближайшем рассмотрении выяснилось, что description
нигде в Swagger UI не используется. После этого решение (в нашем случае *) стало ясным: просто удалите эти описания.
(* В нашей кодовой базе, с чистыми именами классов и методов и т.д., Конечно, не было необходимости в таких "описаниях API" для читателя кода. Я бы допустил наличие этих битов шума, связанного с Swagger, в кодовой базе, если бы они добавили какая-то ценность в Swagger UI, но так как они этого не сделали, единственной разумной вещью было выбросить их.)
Я пробовал вышеуказанные решения, но они не помогли мне.
Чтобы добавить заголовок и описание к документации, вы создаете объекты ApiInfo и Contact, как в примере ниже. Затем вы просто добавляете объект apiInfo в свой список Swagger.
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
@EnableSwagger2
@Configuration
public class SwaggerConfig {
private Contact contact = new Contact("", "", "");
private ApiInfo apiInfo = new ApiInfo(
"Backoffice API documentation",
"This page documents Backoffice RESTful Web Service Endpoints",
"1.0",
"",
contact,
"",
"");
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage(
PaymentsController.class.getPackage().getName()
))
.paths(PathSelectors.ant("/api/v1/payments" + "/**"))
.build()
.useDefaultResponseMessages(false)
.globalOperationParameters(
newArrayList(new ParameterBuilder()
.name("x-authorization")
.description("X-Authorization")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build()));
}
}
Выше код создает описание, как на скриншоте ниже.