1. Обзор
Описание RESTful API играет важную роль в документации. Одним из распространенных инструментов, используемых для документирования REST API, является Swagger 2 . Однако один полезный атрибут, используемый для добавления описания, устарел. В этом руководстве мы найдем решение для устаревшего атрибута описания с помощью Swagger 2 и OpenAPI 3 и покажем, как их можно использовать для описания приложения Spring Boot REST API.
2. Описание API
По умолчанию Swagger создает пустое описание для имени класса REST API. Поэтому нам нужно указать подходящую аннотацию для описания REST API. Мы можем либо использовать Swagger 2 с аннотацией @Api , либо использовать аннотацию @Tag в OpenAPI 3.
3. Чванство 2
Чтобы использовать Swagger 2 для Spring Boot REST API, мы можем использовать библиотеку Springfox . Нам нужно добавить зависимость springfox-boot-starter в файл pom.xml :
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Библиотека Springfox предоставляет аннотацию @Api для настройки класса как ресурса Swagger. Ранее аннотация @Api предоставляла атрибут описания для настройки документации API:
@Api(value = "", description = "")
Однако, как упоминалось ранее, атрибут description устарел . К счастью, есть альтернатива. Мы можем использовать атрибут tags :
@Api(value = "", tags = {"tag_name"})
В Swagger 1.5 мы использовали аннотацию @SwaggerDefinition для определения тега . Однако он больше не поддерживается в Swagger 2. Поэтому в Swagger 2 мы определяем теги и описания в bean- компоненте Docket :
@Configuration
public class SwaggerConfiguration {
public static final String BOOK_TAG = "book service";
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.tags(new Tag(BOOK_TAG, "the book API with description api tag"));
}
}
Здесь мы используем класс Tag в нашем bean-компоненте Docket для создания нашего тега . При этом мы можем ссылаться на тег в нашем контроллере:
@RestController
@RequestMapping("/api/book")
@Api(tags = {SwaggerConfiguration.BOOK_TAG})
public class BookController {
@GetMapping("/")
public List<String> getBooks() {
return Arrays.asList("book1", "book2");
}
}
4. Открытый API 3
OpenAPI 3 — это последняя версия спецификации OpenAPI . Это преемник OpenAPI 2 (Swagger 2). Для описания API с использованием OpenAPI 3 мы можем использовать аннотацию @Tag . Кроме того, аннотация @Tag содержит описание , а также внешние ссылки. Давайте определим класс BookController :
@RestController
@RequestMapping("/api/book")
@Tag(name = "book service", description = "the book API with description tag annotation")
public class BookController {
@GetMapping("/")
public List<String> getBooks() {
return Arrays.asList("book1", "book2");
}
}
5. Вывод
В этой краткой статье мы описали, как добавить описание в REST API в приложении Spring Boot. Мы рассмотрели, как этого можно добиться с помощью Swagger 2 и OpenAPI 3. Для раздела Swagger код доступен на GitHub . Чтобы увидеть пример кода OpenAPI 3, ознакомьтесь с его модулем на GitHub .