YouTube посібник
youtube tutorail
Вступ
Open API (раніше Swagger) — це найпоширеніший у світі стандарт опису API, який надає формальну специфікацію для опису HTTP API.
Це дозволяє людям зрозуміти, як працює API і як послідовність API взаємодіє між собою.
Специфікація є машиночитною, тому ми можемо генерувати клієнтський код, створювати тести і багато іншого...
Специфікація Open API має широке застосування, тому користується підтримкою великої кількості постачальників та інструментів.
Історія
Swagger запропонував специфікацію для опису RESTful API.
Ця специфікація створює RESTful інтерфейс для зручної розробки та використання API, ефективно відображаючи всі ресурси та операції, пов'язані з ним.
Специфікація Swagger була прийнята індустрією і стала стандартом, відомим як специфікація OPEN API.
Специфікація базується на кількох принципах:
- Специфікація повинна бути написана у форматах JSON або YAML.
- Вона призначена для опису RESTful API.
- Мета — зробити специфікацію машиночитною.
- Однак також потрібно зробити її зрозумілою для людей.
Swagger також створив Swagger-ui — популярний веб-інтерфейс користувача для відображення та взаємодії з кінцевими точками.
swagger.io
Ключові моменти в історії специфікації:
- 2010 — Swagger
- 2014 — Open API 2.0
- 2017 — Open API 3.0
- 2019 — springdoc-openapi
- 2021 — Open API 3.1
Spring doc — Open API
springdoc-openapi — це бібліотека, яка дозволяє автоматично генерувати документацію Open API для ваших проектів на Spring.
Вона надає інтерфейс користувача Swagger з переліком ваших кінцевих точок та можливістю генерувати JSON-специфікацію Open API.
Бібліотека доступна як залежність в залежності від того, чи використовуєте ви фреймворки webMvc або webflux, а також чи потрібна вам лише генерація специфікації Open API, чи також інтерфейс користувача Swagger.
У нашому випадку проекту, де використовується фреймворк webMvc, ми хочемо мати можливість генерувати як специфікацію API, так і відображати інтерфейс користувача Swagger, тому ми додали стартер webmvc-ui.
2.7.0
org.springdoc
springdoc-openapi-starter-webmvc-ui
${springdoc.version}
Інтеграція "з коробки"
З коробки бібліотека Spring Doc — Open API інтегрована з рештою екосистеми Spring, і лише додавши бібліотеку як залежність до нашого проекту, ми отримаємо з коробки багатий функціонал.
Для демонстрації можливостей бібліотеки ми створили проект, який має наступні стартери:
webMvc
підтримка веб-додатків, включаючи REST, за допомогою Spring MVC
actuator
вбудовані (або кастомні) кінцеві точки, що дозволяють моніторити та керувати вашим додатком — такі як здоров'я додатку, метрики, сесії тощо.
Spring Data JPA
підтримка збереження даних за допомогою Java Persistence API
validations
підтримка валідації бінів
Ми можемо сказати бібліотеці springdoc-openapi, щоб вона сканувала пакети або включала шляхи з нашого додатку в специфікацію Open API двома способами.
Або вказавши властивості в нашому application.properties:
# Пакети для сканування
springdoc.packagesToScan=com.package1, com.package2
# Шляхи для включення
springdoc.pathsToMatch=/v1, /api/balance/**
або програмно, визначивши бін GroupedOpenApi:
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("springshop-public")
.pathsToMatch("/public/**")
.build();
}
Spring @RestControllers
Ми отримаємо визначення нашого API, просто використовуючи стандартні анотації Spring webMvc та вказавши пакет для сканування бібліотеці springdoc-openapi.
Наприклад, визначення класу:
@RestController
@RequestMapping("/api/v1/email")
public class EmailApiController implements EmailApi {
@Override
@PostMapping
public ResponseEntity sendEmail(@RequestBody @Valid EmailRequest emailRequest) {
return ResponseEntity.ok(new EmailResponse("message-id", "Queued.
Дякую."));
}
@Override
@GetMapping("/{id}")
public ResponseEntity checkStatus(@PathVariable String id) {
return ResponseEntity.ok(id);
}
@GetMapping("/filter")
public Page
Ми покажемо всі кінцеві точки, які надає actuator, і змінемо стандартний кореневий URL для actuator з _/actuator_ на _/management_.
springdoc.show-actuator=true
management.endpoints.web.exposure.include=*
management.endpoints.web.base-path=/management
```
У нашому додатку на Spring специфікація Open API за замовчуванням доступна за адресою: /v3/api-docs, а Swagger UI за адресою: /swagger-ui/index.html
Spring Data JPA
Деякі вбудовані об'єкти фреймворку Spring Data JPA, такі як Page і Pageable, автоматично доступні в описі схеми.
Для визначення методу:
Page
/api/v1/…` і не має стандартного веб-інтерфейсу, ми можемо відобразити Swagger за замовчуванням на кореневому URL, встановивши властивість:
Відкриває Swagger UI на базовому URL
springdoc.swagger-ui.use-root-path=true
```
Налаштування визначення REST API
Додавши анотації springdoc-openapi до визначень наших класів і методів, наприклад:
@Operation@ApiResponse@RequestBody- …
ми можемо додатково налаштувати, як описано наше API в Open API і Swagger UI.
Особливо корисною є частина @RequestBody content, де ми можемо використовувати @ExampleObject, щоб надати користувачам валідний приклад JSON для негайного тестування нашого API.
Приклад налаштування методу:
@Operation(summary = "надсилає email", tags = {"email"}
, description = """
надсилає email на адресу
з темою
і текстом
""")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "email успішно надіслано",
content = @Content(schema = @Schema(implementation = EmailRequest.class)
, examples = @ExampleObject(value = """
{
"id": "message-id",
"message": "Queued. Thank you."
}
""")))
})
ResponseEntity sendEmail(
@RequestBody(
description = "email повідомлення",
content = @Content(examples = @ExampleObject(value = """
{
"to": "[email protected]",
"subject": "тестовий лист",
"text": "Ласкаво просимо на наш сайт!"
}
""")))
EmailRequest emailRequest);
Посилання на GitHub:
https://github.com/kanezi/springdoc-openapi-showcase
Перекладено з: Documenting RESTful APIs in Spring with Open API spec