junior
Как документировать API и архитектурные решения?
Документация API генерируется автоматически из кода через springdoc-openapi, а архитектурные решения фиксируются в ADR (Architecture Decision Records) рядом с кодом.
Аналогия из жизни: ADR — это как протокол заседания совета директоров. Через год никто не помнит, почему выбрали Kafka, а не RabbitMQ — но если есть протокол с аргументами, ответ очевиден.
springdoc-openapi
Пример
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Order Service API")
.version("1.0.0")
.description("API для управления заказами"))
.addSecurityItem(new SecurityRequirement().addList("bearer-jwt"))
.components(new Components()
.addSecuritySchemes("bearer-jwt",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));
}
}
Аннотации на контроллере
Пример
@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Управление заказами")
public class OrderController {
@Operation(summary = "Создать заказ")
@ApiResponses({
@ApiResponse(responseCode = "201", description = "Заказ создан"),
@ApiResponse(responseCode = "400", description = "Некорректный запрос",
content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
})
@PostMapping
public ResponseEntity<OrderResponse> createOrder(
@Valid @RequestBody CreateOrderRequest request) { ... }
}
Architecture Decision Records (ADR)
Пример
# ADR-001: Использование PostgreSQL в качестве основной БД
Статус: Принято (2026-01-15)
Контекст: Нужно выбрать основную реляционную СУБД.
Решение: Используем PostgreSQL 17.
Причины:
- Лучшая поддержка JSONB для гибких атрибутов
- Managed-сервисы во всех облаках
- Лицензия (PostgreSQL License, аналог MIT)
Последствия:
- Миграции через Flyway
- Мониторинг через pg_stat_statements
Структура документации в проекте
Пример
docs/
adr/
0001-use-postgresql.md
0002-hexagonal-architecture.md
0003-kafka-for-events.md
template.md
Ключевые принципы
- Документация API генерируется из кода (springdoc-openapi). Ручная документация устаревает
- ADR — минимально необходимая архитектурная документация. Фиксирует “почему”, а не “что”
- README — точка входа. Если за 10 минут нельзя поднять проект, README плохой
- Docs-as-code: документация в git, рядом с кодом, версионируется вместе с ним
Частые ошибки
- Ручное написание OpenAPI-спецификации, которая расходится с API
- Избыточная документация, которую никто не обновляет
- Отсутствие ADR: через год никто не помнит причины решений
- Документация только в Confluence: не версионируется с кодом
На собеседовании: два ключевых пункта: 1) API-документация генерируется из кода (springdoc-openapi), 2) архитектурные решения фиксируются в ADR. Если спросят “Зачем ADR?” — ответ: фиксирует контекст и причины решений, которые дорого менять. Новый разработчик читает ADR и понимает “почему Kafka, а не RabbitMQ” без созвона с архитектором.