[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"question-rest-api-kak-dokumentirovat-rest-api-s-pomoshchyu-swagger-openapi":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},1222,"kak-dokumentirovat-rest-api-s-pomoshchyu-swagger-openapi",34,"rest-api","REST API","🌐","Как документировать REST API с помощью Swagger\u002FOpenAPI?","OpenAPI Specification (ранее Swagger Specification) — стандарт описания REST API в формате JSON или YAML. Swagger — набор инструментов для работы с OpenAPI (Swagger UI, Swagger Editor, Swagger Codegen).\n\n### Основные инструменты\n\n- Swagger UI — интерактивная веб-документация с возможностью отправки запросов.\n- OpenAPI Generator \u002F Swagger Codegen — генерация клиентов и серверов из спецификации.\n- Springdoc-openapi — библиотека для автоматической генерации OpenAPI-документации в Spring Boot.\n\n### Настройка в Spring Boot (springdoc-openapi)\n\n```xml\n\u003Cdependency>\n    \u003CgroupId>org.springdoc\u003C\u002FgroupId>\n    \u003CartifactId>springdoc-openapi-starter-webmvc-ui\u003C\u002FartifactId>\n    \u003Cversion>2.5.0\u003C\u002Fversion>\n\u003C\u002Fdependency>\n```\n\nПосле подключения доступны:\n- `http:\u002F\u002Flocalhost:8080\u002Fswagger-ui.html` — Swagger UI.\n- `http:\u002F\u002Flocalhost:8080\u002Fv3\u002Fapi-docs` — OpenAPI-спецификация в JSON.\n\n\u003Cdetails>\u003Csummary>Аннотации для документирования\u003C\u002Fsummary>\n\n```java\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fusers\")\n@Tag(name = \"Users\", description = \"Управление пользователями\")\npublic class UserController {\n\n    @Operation(\n        summary = \"Получить пользователя по ID\",\n        description = \"Возвращает полную информацию о пользователе\"\n    )\n    @ApiResponses({\n        @ApiResponse(responseCode = \"200\", description = \"Пользователь найден\",\n            content = @Content(schema = @Schema(implementation = UserDto.class))),\n        @ApiResponse(responseCode = \"404\", description = \"Пользователь не найден\",\n            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))\n    })\n    @GetMapping(\"\u002F{id}\")\n    public ResponseEntity\u003CUserDto> getUser(\n            @Parameter(description = \"ID пользователя\", example = \"42\")\n            @PathVariable Long id) {\n        return ResponseEntity.ok(userService.findById(id));\n    }\n\n    @Operation(summary = \"Создать нового пользователя\")\n    @ApiResponse(responseCode = \"201\", description = \"Пользователь создан\")\n    @PostMapping\n    public ResponseEntity\u003CUserDto> createUser(\n            @RequestBody @Valid CreateUserRequest request) {\n        UserDto created = userService.create(request);\n        URI location = URI.create(\"\u002Fapi\u002Fusers\u002F\" + created.id());\n        return ResponseEntity.created(location).body(created);\n    }\n}\n```\n\nДокументирование модели:\n```java\n@Schema(description = \"Запрос на создание пользователя\")\npublic record CreateUserRequest(\n    @Schema(description = \"Имя пользователя\", example = \"Иван Петров\")\n    @NotBlank String name,\n\n    @Schema(description = \"Email\", example = \"ivan@example.com\")\n    @Email String email,\n\n    @Schema(description = \"Возраст\", minimum = \"18\", maximum = \"120\")\n    @Min(18) Integer age\n) {}\n```\n\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(\"User Service API\")\n                .version(\"1.0.0\")\n                .description(\"API для управления пользователями\"))\n            .addSecurityItem(new SecurityRequirement().addList(\"Bearer\"))\n            .components(new Components()\n                .addSecuritySchemes(\"Bearer\",\n                    new SecurityScheme()\n                        .type(SecurityScheme.Type.HTTP)\n                        .scheme(\"bearer\")\n                        .bearerFormat(\"JWT\")));\n    }\n}\n```\n\n\u003C\u002Fdetails>\n\n> **На собеседовании:** нужно знать разницу между OpenAPI (спецификация) и Swagger (инструменты), уметь назвать ключевые аннотации (@Operation, @Tag, @Schema). Частая ошибка — путать Swagger и OpenAPI или не знать про springdoc-openapi для Spring Boot 3.","","middle",[15],"rest",[],null,{"title":19,"description":20,"ogTitle":19,"ogDescription":21,"keywords":22,"schemaAnswer":23,"featuredSnippetReady":24},"Как документировать REST API с помощью Swagger\u002FOpenAPI? — Gymterview","OpenAPI Specification (ранее Swagger Specification) — стандарт описания REST API в формате JSON или YAML. Swagger — набор инструментов для работы с OpenAPI (Swa","OpenAPI Specification (ранее Swagger Specification) — стандарт описания REST API в формате JSON или YAML. Swagger — набо",[15,13],"OpenAPI Specification (ранее Swagger Specification) — стандарт описания REST API в формате JSON или YAML. Swagger — набор инструментов для работы с OpenAPI (Swagger UI, Swagger Editor, Swagger Codegen).",true]