[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"question-sovremennaya-razrabotka-web-kak-dokumentirovat-api-i-arkhitekturnye-resheniya":3},{"id":4,"slug":5,"topicId":6,"topicSlug":7,"topicName":8,"topicEmoji":9,"question":10,"answer":11,"codeLang":12,"codeSrc":12,"important":12,"commonMistakes":12,"modernUsage":12,"difficulty":13,"tags":14,"related":20,"progress":21,"seo":22},1200,"kak-dokumentirovat-api-i-arkhitekturnye-resheniya",37,"sovremennaya-razrabotka-web","Современная разработка WEB","🌐","Как документировать API и архитектурные решения?","Документация API генерируется автоматически из кода через springdoc-openapi, а архитектурные решения фиксируются в ADR (Architecture Decision Records) рядом с кодом.\n\n> Аналогия из жизни: ADR — это как протокол заседания совета директоров. Через год никто не помнит, почему выбрали Kafka, а не RabbitMQ — но если есть протокол с аргументами, ответ очевиден.\n\n### springdoc-openapi\n\n```java\n@Configuration\npublic class OpenApiConfig {\n\n    @Bean\n    public OpenAPI customOpenAPI() {\n        return new OpenAPI()\n            .info(new Info()\n                .title(\"Order Service API\")\n                .version(\"1.0.0\")\n                .description(\"API для управления заказами\"))\n            .addSecurityItem(new SecurityRequirement().addList(\"bearer-jwt\"))\n            .components(new Components()\n                .addSecuritySchemes(\"bearer-jwt\",\n                    new SecurityScheme()\n                        .type(SecurityScheme.Type.HTTP)\n                        .scheme(\"bearer\")\n                        .bearerFormat(\"JWT\")));\n    }\n}\n```\n\n### Аннотации на контроллере\n\n```java\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fv1\u002Forders\")\n@Tag(name = \"Orders\", description = \"Управление заказами\")\npublic class OrderController {\n\n    @Operation(summary = \"Создать заказ\")\n    @ApiResponses({\n        @ApiResponse(responseCode = \"201\", description = \"Заказ создан\"),\n        @ApiResponse(responseCode = \"400\", description = \"Некорректный запрос\",\n            content = @Content(schema = @Schema(implementation = ProblemDetail.class)))\n    })\n    @PostMapping\n    public ResponseEntity\u003COrderResponse> createOrder(\n            @Valid @RequestBody CreateOrderRequest request) { ... }\n}\n```\n\n### Architecture Decision Records (ADR)\n\n```markdown\n# ADR-001: Использование PostgreSQL в качестве основной БД\n\nСтатус: Принято (2026-01-15)\n\nКонтекст: Нужно выбрать основную реляционную СУБД.\n\nРешение: Используем PostgreSQL 17.\n\nПричины:\n- Лучшая поддержка JSONB для гибких атрибутов\n- Managed-сервисы во всех облаках\n- Лицензия (PostgreSQL License, аналог MIT)\n\nПоследствия:\n- Миграции через Flyway\n- Мониторинг через pg_stat_statements\n```\n\n### Структура документации в проекте\n\n```\ndocs\u002F\n  adr\u002F\n    0001-use-postgresql.md\n    0002-hexagonal-architecture.md\n    0003-kafka-for-events.md\n    template.md\n```\n\n### Ключевые принципы\n\n- Документация API генерируется из кода (springdoc-openapi). Ручная документация устаревает\n- ADR — минимально необходимая архитектурная документация. Фиксирует \"почему\", а не \"что\"\n- README — точка входа. Если за 10 минут нельзя поднять проект, README плохой\n- Docs-as-code: документация в git, рядом с кодом, версионируется вместе с ним\n\n### Частые ошибки\n\n- Ручное написание OpenAPI-спецификации, которая расходится с API\n- Избыточная документация, которую никто не обновляет\n- Отсутствие ADR: через год никто не помнит причины решений\n- Документация только в Confluence: не версионируется с кодом\n\n> **На собеседовании:** два ключевых пункта: 1) API-документация генерируется из кода (springdoc-openapi), 2) архитектурные решения фиксируются в ADR. Если спросят \"Зачем ADR?\" — ответ: фиксирует контекст и причины решений, которые дорого менять. Новый разработчик читает ADR и понимает \"почему Kafka, а не RabbitMQ\" без созвона с архитектором.","","junior",[15,16,17,18,19],"openapi","documentation","best-practices","spring-boot","adr",[],null,{"title":23,"description":24,"ogTitle":25,"ogDescription":26,"keywords":27,"schemaAnswer":37,"featuredSnippetReady":38},"Как документировать API и архитектурные решения — Gymterview","Документация API через springdoc-openapi: автогенерация из кода. ADR (Architecture Decision Records) для фиксации архитектурных решений. Docs-as-code подход.","Документация API и архитектурных решений: springdoc-openapi и ADR — Gymterview","API-документация из кода (springdoc-openapi) + ADR для архитектурных решений. Docs-as-code подход.",[28,29,30,31,32,33,34,35,36],"springdoc-openapi","API документация","ADR","Architecture Decision Records","OpenAPI","Swagger UI","docs-as-code","Spring Boot","собеседование","API-документация генерируется из кода через springdoc-openapi с аннотациями @Operation, @ApiResponse, @Tag. Архитектурные решения фиксируются в ADR (Architecture Decision Records) — минимальная документация, объясняющая 'почему', а не 'что'. Docs-as-code: документация в git рядом с кодом. README — точка входа, проект должен подниматься за 10 минут.",true]