Spring Boot: Spring Doc генерирует документацию OpenAPI3.0

Spring Boot

1 Обзор

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

2. Настройте springdoc-openapi

Если хотитеspringdoc-openapiЧтобы сгенерировать стандартную документацию OpenAPI 3 для нашего API, просто добавьтеspringdoc-openapi-coreзависит отpom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-core</artifactId>
    <version>1.1.45</version>
</dependency>

После завершения добавления запустите приложение, чтобы получить доступ к пути по умолчанию. /v3/api-docsОзнакомьтесь с документацией следующим образом:

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

Если вы хотите настроить путь, вы можетеapplication.propertiesуказано в файле:

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

Таким образом, путь доступа к документу становится:

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

openapi3

OpenAPI по умолчанию определяется в формате JSON. заyamlФормат, вы можете получить доступ к следующему пути, чтобы получить:

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

3. Интегрируйте springdoc-openapi и пользовательский интерфейс Swagger

Помимо самодельныхOpenAPI 3В дополнение к спецификации, мы также можемspringdoc-openapiиSwagger UIИнтегрируйте вместе, чтобы вы могли взаимодействовать с нашей спецификацией API и конечными точками тестирования.

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

интегрироватьspringdoc-openapiиSwagger UI, остается только добавитьspringdoc-openapi-uiЗависит от файла проекта pom.xml.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.45</version>
</dependency>

Посетите страницу swagger-ui:

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

Конечно, вы также можете настроить путь доступа, как указано выше:

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

3.2 Возьми каштан

Предположим, есть контроллер для мяча (сборной по футболу грустно, поэтому ей нужен мяч!!).

@RestController
@RequestMapping("/api/ball")
public class BallController {
 
    @Autowired
    private BallRepository repository;
 
    @GetMapping("/{id}")
    public Ball findById(@PathVariable long id) {
        return repository.findById(id)
            .orElseThrow(() -> new BallNotFoundException());
    }
 
    @GetMapping("/")
    public Collection<Book> 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

Интерфейс swagger-ui:

![swagger-ui](https://www.baeldung.com/wp-content/uploads/2019/11/1-swagger-ui.png)

4. Springdoc-openapi интегрируется с Spring WebFlux.

Мы можем добавить зависимости к проекту Spring WebFlux следующим образом:springdoc-openapi-webflux-uiиspringdoc-openapi and Swagger UIинтегрированный:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.1.45</version>
</dependency>

Затем браузер обращается к адресу

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

Точно так же, добавляяspringdoc.swagger-ui.pathэлемент конфигурации дляapplication.propertiesфайл для настройки пути доступа к документу.

5. Используйтеspringdoc-openapiПлагин Maven

springdoc-openapiбиблиотека предоставляетspringdoc-openapi-maven-pluginПлагин для создания описаний Open API в формате JSON или yaml.

springdoc-openapi-maven-pluginзависит отspring-boot-mavenПлагины Maven запускает плагин openapi на этапе интеграционного тестирования.

Итак, какpom.xmlА как насчет плагина конфигурации? См. код ниже:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.1.8.RELEASE</version>
    <executions>
        <execution>
            <id>pre-integration-test</id>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>post-integration-test</id>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>0.2</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Конечно, плагины также можно настроить с помощью пользовательских значений:

<plugin>
    <executions>
        .........
    </executions>
    <configuration> 
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl> 
        <outputFileName>openapi.json</outputFileName> 
        <outputDir>${project.build.directory}</outputDir> 
    </configuration>
</plugin>

Обратите внимание на несколько параметров, которые мы настраиваем в плагине:

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

6. Автоматически создавать документацию с помощью JSR-303 Bean Validation

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

Возьмите каштан:

public class Ball {
 
    private long id;
 
    @NotBlank
    @Size(min = 0, max = 20)
    private String title;
 
    @NotBlank
    @Size(min = 0, max = 30)
    private String author;
 
}

заBallДокументация, сгенерированная bean-компонентом, более информативна:schema

7. Используйте @ControllerAdvice и @ResponseStatus для создания документации

существует@RestControllerAdviceВ аннотированном классе используйте его в методе@ResponseStatusДокументация с кодами статуса возврата генерируется автоматически. следующее@ControllerAdviceВ аннотированном классе@ResponseStatusДва метода модификации:

@RestControllerAdvice
public class GlobalControllerExceptionHandler {
 
    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<String> handleConnversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
     
    @ExceptionHandler(BallNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity<String> handleBallNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

Теперь мы можем видеть в документации, что коды возврата — 400 и 404.not-found

8. Резюме

Версия Spring Boot 2.2.x в настоящее время может не поддерживаться, поэтому при ее использовании лучше использовать версию 2.1.x.В этой статье используется Spring Boot версии 2.1.8.RELEASE.

Приведенный выше код можно найти в моем github,over on GitHub.

Обратите внимание на общедоступный номер: ответьте 666, чтобы получить преимущества переведенных статей:img

Категории