Документирование API Spring REST с использованием OpenAPI 3.0

Автор оригинала: baeldung.

1. Обзор

Документация является неотъемлемой частью создания API REST. В этом уроке мы рассмотрим SpringDoc — инструмент, который упрощает создание и обслуживание документов API на основе спецификации OpenAPI 3 для приложений Spring Boot 1.x и 2.x.

Дальнейшее чтение:

Создайте клиент Spring Boot REST с помощью Swagger

Настройка Swagger 2 с помощью API Spring REST

Введение в контракт Spring Cloud

2. Настройка spring doc-openapi

Чтобы spring doc-open api автоматически генерировал документы спецификации OpenAPI3 для нашего API, мы просто добавляем зависимость springdoc-openapi-ui в наш pom.xml :

    org.springdoc
    springdoc-openapi-ui
    1.5.2

Затем, когда мы запустим наше приложение, открытые описания API будут доступны по пути /v3/api-docs по умолчанию:

http://localhost:8080/v3/api-docs/

Чтобы использовать пользовательский путь, мы можем указать его в файле application.properties :

springdoc.api-docs.path=/api-docs

Теперь мы сможем получить доступ к документам по адресу:

http://localhost:8080/api-docs/

Определения открытого API по умолчанию представлены в формате JSON . Для формата yaml мы можем получить определения по адресу:

http://localhost:8080/api-docs.yaml

3. Настройка spring doc-open api с интерфейсом Swagger

Помимо создания самой спецификации OpenAPI3, мы можем интегрировать spring doc-open api с пользовательским интерфейсом Swagger, чтобы мы могли взаимодействовать с нашей спецификацией API и использовать конечные точки.

3.1. Зависимость Maven

Все, что нам нужно сделать, чтобы настроить spring doc-open api с помощью Swagger UI,-это добавить зависимость spring doc-openapi-ui в проект pom.xml :

    org.springdoc
    springdoc-openapi-ui
    1.5.2

Теперь мы можем получить доступ к документации API по адресу:

http://localhost:8080/swagger-ui.html

3.2. Поддержка свойств пользовательского интерфейса swagger

Spring doc-open api также поддерживает swagger-ui свойства . Они могут использоваться в качестве свойств загрузки Spring с префиксом spring doc.swagger-ui .

Например, давайте настроим путь к нашей документации по API. Мы можем сделать это, изменив наш application.properties , чтобы включить:

springdoc.swagger-ui.path=/swagger-ui-custom.html

Итак, теперь наша документация по API будет доступна по адресу http://localhost:8080/swagger-ui-custom.html .

В качестве другого примера, чтобы отсортировать пути API в порядке их HTTP-методов, мы можем добавить:

springdoc.swagger-ui.operationsSorter=method

3.3. Пример API

Предположим, в нашем приложении есть контроллер для управления Книгой s:

@RestController
@RequestMapping("/api/book")
public class BookController {

    @Autowired
    private BookRepository repository;

    @GetMapping("/{id}")
    public Book findById(@PathVariable long id) {
        return repository.findById(id)
            .orElseThrow(() -> new BookNotFoundException());
    }

    @GetMapping("/")
    public Collection findBooks() {
        return repository.getBooks();
    }

    @PutMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Book updateBook(
      @PathVariable("id") final String id, @RequestBody final Book book) {
        return book;
    }
}

Затем, когда мы запустим наше приложение, мы сможем просмотреть документацию по адресу:

http://localhost:8080/swagger-ui-custom.html

Давайте перейдем к конечной точке /api/book и посмотрим подробности ее запроса и ответа:

4. Интеграция spring doc-open api С Spring Web Flux

Мы можем интегрировать spring doc-open api и Swagger UI в проект Spring WebFlux, добавив spring doc-openapi-webflux-ui :

    org.springdoc
    springdoc-openapi-webflux-ui
    1.5.2

Как и прежде, документы будут доступны по адресу:

http://localhost:8080/swagger-ui.html

Чтобы настроить путь, мы могли бы снова добавить spring doc.swagger-ui.путь свойство в нашем приложении.свойства .

5. Раскрытие Информации О Разбиении На Страницы

Spring Data JPA довольно легко интегрируется с Spring MVC. Одним из примеров такой интеграции является Pageable поддержка:

@GetMapping("/filter")
public Page filterBooks(Pageable pageable) {
     return repository.getBooks(pageable);
}

Сначала мы могли бы ожидать, что Spring Doc добавит page , size и sort параметры запроса в сгенерированную документацию. Однако по умолчанию Spring Doc не соответствует этим ожиданиям. Чтобы разблокировать эту функцию, мы должны добавить зависимость spring doc-openapi-data-rest :

    org.springdoc
    springdoc-openapi-data-rest
    1.5.2

Теперь он добавляет ожидаемые параметры запроса в документацию:

6. Использование плагина spring doc-open api Maven

Библиотека spring doc-open api предоставляет плагин Maven spring doc-open api-maven-plugin для создания описаний OpenAPI в форматах json и yaml .

Плагин spring doc-open api-maven-plugin работает с плагином spring-boot-maven . Maven запускает плагин openapi во время фазы integration-test|/.

Давайте посмотрим, как мы можем настроить плагин в вашем pom.xml :

    org.springframework.boot
    spring-boot-maven-plugin
    2.3.3.RELEASE
    
        
            pre-integration-test
            
                start
            
        
        
            post-integration-test
            
                stop
            
        
    


    org.springdoc
    springdoc-openapi-maven-plugin
    0.2
    
        
            integration-test
            
                generate
            
        
    

Мы также можем настроить плагин для использования пользовательских значений:

    
        .........
    
     
        http://localhost:8080/v3/api-docs 
        openapi.json 
        ${project.build.directory} 
    

Давайте подробнее рассмотрим параметры, которые мы можем настроить для плагина:

• apiDocsUrl – URL-адрес, по которому можно получить доступ к документам в формате JSON, по умолчанию http://localhost:8080/v3/api-docs
• outputFileName – Имя файла, в котором хранятся определения, по умолчанию openapi.json
• outputDir – Абсолютный путь к каталогу, в котором хранятся документы, по умолчанию ${project.build.directory}

7. Автоматическое Создание Документов С Использованием Проверки Компонентов JSR-303

Когда наша модель включает аннотации проверки компонентов JSR-303, такие как @NotNull , @NotBlank , @Size , @Min и @Max , библиотека spring doc-openapi использует их для создания дополнительной документации схемы для соответствующих ограничений.

Давайте рассмотрим пример, используя наш Book bean:

public class Book {

    private long id;

    @NotBlank
    @Size(min = 0, max = 20)
    private String title;

    @NotBlank
    @Size(min = 0, max = 30)
    private String author;

}

Теперь документация, сгенерированная для Book bean, немного более информативна:

Схема Книги После Добавления Проверки Компонента

Использование методов @ResponseStatus on в классе @RestControllerAdvice автоматически создаст документацию для кодов ответов. В этом классе @Pestcontroladvice оба метода аннотируются с помощью @ResponseStatus :

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity handleConnversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
    
    @ExceptionHandler(BookNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity handleBookNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

В результате теперь мы можем видеть документацию по кодам ответов 400 и 404:

9. Создание документации с использованием @Operation и @ApiResponses

Далее давайте посмотрим, как мы можем добавить некоторое описание в наш API, используя пару Открытых аннотаций, специфичных для API|/.

Для этого мы аннотируем /api/book/{id} конечную точку нашего контроллера с помощью @Operation и @ApiResponses :

@Operation(summary = "Get a book by its id")
@ApiResponses(value = { 
  @ApiResponse(responseCode = "200", description = "Found the book", 
    content = { @Content(mediaType = "application/json", 
      schema = @Schema(implementation = Book.class)) }),
  @ApiResponse(responseCode = "400", description = "Invalid id supplied", 
    content = @Content), 
  @ApiResponse(responseCode = "404", description = "Book not found", 
    content = @Content) })
@GetMapping("/{id}")
public Book findById(@Parameter(description = "id of book to be searched") 
  @PathVariable long id) {
    return repository.findById(id).orElseThrow(() -> new BookNotFoundException());
}

Вот какой эффект:

Как мы видим, текст, который мы добавили в @Operation , находится на уровне операции API. Аналогично, описание, добавленное к различным элементам @ApiResponse в аннотации контейнера @ApiResponses , также видно здесь, добавляя смысл нашим ответам API.

Очевидно, мы не получаем никакой схемы для ответов 400 и 404 выше. Поскольку мы определили для них пустой @Content , отображаются только их описания.

10. Поддержка Kotlin

Поскольку Spring Boot 2.x имеет первоклассную поддержку Kotlin, Spring Doc поддерживает этот язык JVM из коробки для приложений Boot 2.x.

Чтобы увидеть это в действии, мы создадим простой Foo API в Kotlin.

После начальной настройки мы добавим класс данных и контроллер. Мы добавим их в подпакет нашего приложения для стендов, чтобы при запуске он забирал наш FooController вместе с предыдущим BookController :

@Entity
data class Foo(
    @Id
    val id: Long = 0,
    
    @NotBlank
    @Size(min = 0, max = 50)
    val name: String = ""
)

@RestController
@RequestMapping("/")
class FooController() {
    val fooList: List = listOf(Foo(1, "one"), Foo(2, "two"))

    @Operation(summary = "Get all foos")
    @ApiResponses(value = [
	ApiResponse(responseCode = "200", description = "Found Foos", content = [
            (Content(mediaType = "application/json", array = (
                ArraySchema(schema = Schema(implementation = Foo::class)))))]),
	ApiResponse(responseCode = "400", description = "Bad request", content = [Content()]),
	ApiResponse(responseCode = "404", description = "Did not find any Foos", content = [Content()])]
    )
    @GetMapping("/foo")
    fun getAllFoos(): List = fooList
}

Теперь, когда мы перейдем по URL-адресу документации по API, мы также увидим Foo API:

Чтобы усилить поддержку типов Kotlin, мы можем добавить эту зависимость:

    org.springdoc
    springdoc-openapi-kotlin1.3.9

После этого наша схема Foo будет выглядеть более информативной, как это было, когда мы добавили проверку компонентов JSR-303:

11. Заключение

В этой статье мы научились настраивать api spring doc-open в наших проектах. Затем мы увидели, как интегрировать spring doc-open api с пользовательским интерфейсом Swagger. Мы также видели, как это сделать с помощью Spring Web fluxprojects.

Затем мы использовали плагин spring doc-open api Maven для создания определений OpenAPI для наших API, и мы увидели, как предоставлять информацию о подкачке и сортировке из данных Spring. После этого мы рассмотрели, как spring doc-openapi автоматически генерирует документацию, используя аннотации проверки компонентов JSR 303 и аннотации @ResponseStatus в классе @ControllerAdvice .

Мы также узнали, как добавить описание в наш API, используя несколько аннотаций, специфичных для OpenAPI. Наконец, мы взглянули на поддержку Котлина открытым API.

Spring doc-openapi генерирует документацию API в соответствии со спецификацией OpenAPI3. Кроме того, он также обрабатывает конфигурацию пользовательского интерфейса Swagger для нас, что делает генерацию документов API довольно простой задачей.

Как всегда, код доступен на GitHub .