[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"question-rest-api-chto-takoe-podkhod-api-design-first":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":16,"progress":17,"seo":18},1229,"chto-takoe-podkhod-api-design-first",34,"rest-api","REST API","🌐","Что такое подход API Design First?","API Design First (API-first) — подход к разработке, при котором спецификация API (контракт) создаётся до написания кода. Из спецификации автоматически генерируются серверные интерфейсы, клиентские SDK, документация и тесты.\n\n### API-first vs Code-first\n\n| Характеристика | API-first (Design First) | Code-first |\n|---------------|--------------------------|------------|\n| Последовательность | Спецификация -> Код | Код -> Спецификация (генерируется) |\n| Источник истины | OpenAPI-спецификация | Исходный код (аннотации) |\n| Параллельная разработка | Да (frontend и backend одновременно) | Нет (frontend ждёт backend) |\n| Согласованность | Контракт фиксирован заранее | Контракт может меняться неконтролируемо |\n| Инструменты | OpenAPI Generator, Swagger Codegen | springdoc-openapi, Swagger annotations |\n\n### Преимущества API-first\n\n- Параллельная разработка — frontend и backend работают одновременно.\n- Контракт как документация — спецификация всегда актуальна.\n- Автоматизированное тестирование — тесты генерируются на основе спецификации.\n- Генерация клиентских SDK для любого языка.\n- Раннее обнаружение ошибок — несовместимые изменения обнаруживаются на этапе проектирования.\n\n\u003Cdetails>\u003Csummary>Пример OpenAPI-спецификации\u003C\u002Fsummary>\n\n```yaml\nopenapi: 3.0.3\ninfo:\n  title: User Service API\n  version: 1.0.0\n  description: API для управления пользователями\n\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\n\npaths:\n  \u002Fusers:\n    get:\n      operationId: getUsers\n      summary: Получить список пользователей\n      tags:\n        - Users\n      parameters:\n        - name: status\n          in: query\n          required: false\n          schema:\n            type: string\n            enum: [ACTIVE, INACTIVE, BLOCKED]\n        - name: page\n          in: query\n          schema:\n            type: integer\n            default: 0\n        - name: size\n          in: query\n          schema:\n            type: integer\n            default: 20\n      responses:\n        '200':\n          description: Список пользователей\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: '#\u002Fcomponents\u002Fschemas\u002FUserPage'\n    post:\n      operationId: createUser\n      summary: Создать пользователя\n      tags:\n        - Users\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: '#\u002Fcomponents\u002Fschemas\u002FCreateUserRequest'\n      responses:\n        '201':\n          description: Пользователь создан\n          headers:\n            Location:\n              schema:\n                type: string\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: '#\u002Fcomponents\u002Fschemas\u002FUserDto'\n        '400':\n          description: Ошибка валидации\n\ncomponents:\n  schemas:\n    CreateUserRequest:\n      type: object\n      required: [name, email]\n      properties:\n        name:\n          type: string\n          minLength: 1\n          maxLength: 100\n        email:\n          type: string\n          format: email\n        age:\n          type: integer\n          minimum: 18\n\n    UserDto:\n      type: object\n      properties:\n        id:\n          type: integer\n          format: int64\n        name:\n          type: string\n        email:\n          type: string\n        age:\n          type: integer\n        createdAt:\n          type: string\n          format: date-time\n\n    UserPage:\n      type: object\n      properties:\n        content:\n          type: array\n          items:\n            $ref: '#\u002Fcomponents\u002Fschemas\u002FUserDto'\n        totalElements:\n          type: integer\n          format: int64\n        totalPages:\n          type: integer\n\n  securitySchemes:\n    BearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n\nsecurity:\n  - BearerAuth: []\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\u003Csummary>Настройка генерации кода в Spring Boot (Maven)\u003C\u002Fsummary>\n\n```xml\n\u003Cplugin>\n    \u003CgroupId>org.openapitools\u003C\u002FgroupId>\n    \u003CartifactId>openapi-generator-maven-plugin\u003C\u002FartifactId>\n    \u003Cversion>7.5.0\u003C\u002Fversion>\n    \u003Cexecutions>\n        \u003Cexecution>\n            \u003Cgoals>\n                \u003Cgoal>generate\u003C\u002Fgoal>\n            \u003C\u002Fgoals>\n            \u003Cconfiguration>\n                \u003CinputSpec>${project.basedir}\u002Fsrc\u002Fmain\u002Fresources\u002Fopenapi\u002Fapi.yaml\u003C\u002FinputSpec>\n                \u003CgeneratorName>spring\u003C\u002FgeneratorName>\n                \u003CapiPackage>com.example.api\u003C\u002FapiPackage>\n                \u003CmodelPackage>com.example.model\u003C\u002FmodelPackage>\n                \u003CconfigOptions>\n                    \u003CinterfaceOnly>true\u003C\u002FinterfaceOnly>\n                    \u003CuseSpringBoot3>true\u003C\u002FuseSpringBoot3>\n                    \u003CuseTags>true\u003C\u002FuseTags>\n                    \u003CopenApiNullable>false\u003C\u002FopenApiNullable>\n                    \u003CskipDefaultInterface>false\u003C\u002FskipDefaultInterface>\n                \u003C\u002FconfigOptions>\n            \u003C\u002Fconfiguration>\n        \u003C\u002Fexecution>\n    \u003C\u002Fexecutions>\n\u003C\u002Fplugin>\n```\n\nСгенерированный интерфейс:\n```java\n@Tag(name = \"Users\", description = \"Управление пользователями\")\n@Generated(\"org.openapitools.codegen\")\npublic interface UsersApi {\n\n    @Operation(summary = \"Получить список пользователей\")\n    @GetMapping(value = \"\u002Fusers\", produces = \"application\u002Fjson\")\n    ResponseEntity\u003CUserPage> getUsers(\n        @RequestParam(required = false) String status,\n        @RequestParam(defaultValue = \"0\") Integer page,\n        @RequestParam(defaultValue = \"20\") Integer size\n    );\n\n    @Operation(summary = \"Создать пользователя\")\n    @PostMapping(value = \"\u002Fusers\", consumes = \"application\u002Fjson\", produces = \"application\u002Fjson\")\n    ResponseEntity\u003CUserDto> createUser(@Valid @RequestBody CreateUserRequest request);\n}\n```\n\nРеализация:\n```java\n@RestController\n@RequiredArgsConstructor\npublic class UsersApiController implements UsersApi {\n\n    private final UserService userService;\n\n    @Override\n    public ResponseEntity\u003CUserPage> getUsers(String status, Integer page, Integer size) {\n        UserPage users = userService.findAll(status, page, size);\n        return ResponseEntity.ok(users);\n    }\n\n    @Override\n    public ResponseEntity\u003CUserDto> createUser(CreateUserRequest request) {\n        UserDto created = userService.create(request);\n        URI location = URI.create(\"\u002Fusers\u002F\" + created.getId());\n        return ResponseEntity.created(location).body(created);\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\n### Частые ошибки\n\n- Генерация полного сервера вместо `interfaceOnly` — приводит к нечитаемому коду.\n- Редактирование сгенерированного кода вручную — изменения будут перезаписаны.\n- Расхождение спецификации и реализации — нужна CI\u002FCD проверка (contract testing).\n\n### Как используется в 2026\n\n- API-first стал стандартом де-факто в крупных компаниях и микросервисных архитектурах.\n- OpenAPI Generator 7.x поддерживает Spring Boot 3.x, Jakarta EE, virtual threads.\n- Spectral и Redocly CLI используются для линтинга спецификаций в CI\u002FCD.\n- AsyncAPI — аналог OpenAPI для асинхронных API (Kafka, RabbitMQ, WebSocket).\n\n> **На собеседовании:** нужно объяснить разницу между API-first и Code-first, назвать преимущества API-first (параллельная разработка, контракт как единый источник истины) и упомянуть `interfaceOnly=true`. Частая ошибка — не знать про OpenAPI Generator или путать его со Swagger Codegen.","","senior",[15],"rest",[],null,{"title":19,"description":20,"ogTitle":19,"ogDescription":21,"keywords":22,"schemaAnswer":23,"featuredSnippetReady":24},"Что такое подход API Design First? — Gymterview","API Design First (API-first) — подход к разработке, при котором спецификация API (контракт) создаётся до написания кода. Из спецификации автоматически генерирую","API Design First (API-first) — подход к разработке, при котором спецификация API (контракт) создаётся до написания кода.",[15,13],"API Design First (API-first) — подход к разработке, при котором спецификация API (контракт) создаётся до написания кода. Из спецификации автоматически генерируются серверные интерфейсы, клиентские SDK, документация и тесты.",true]