Документирование API с помощью Swagger на Springboot

Введение

В предыдущей статье мы уже узнали, как создать Rest API с помощью Springboot и MySql .

В этой статье мы узнаем, как создать документацию API с помощью Swagger на Springboot, а также протестируем все apis с помощью swagger ui. посмотрите на изображение ниже для простого описания того, что мы создадим.

Springboot + Swagger-UI

Swagger-UI home pge

Требования

• Maven 3+
• Java 8+
• IDE (Intelij Idea )
• Mysql сервер
• (для тестового пользовательского интерфейса Swagger)

Обзоры

• Откройте проект Springboot + Mysql
• Добавьте зависимость и конфигурацию swagger
• добавьте аннотацию swagger на класс контроллера
• Протестируйте все Rest API с помощью Swagger UI
• Полный исходный код здесь

Открытый проект Springboot + Mysql

свяжите проект springboot + Mysql

Добавление зависимостей и конфигурации Swagger

• шаг 1, откройте файл pom.xml, а затем добавьте зависимости следующим образом

<!-- swagger open api-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.10</version>
        </dependency>

• шаг 2, откройте файл application.properties, а затем добавьте синтаксис следующим образом.

# for enable the swagger-ui page (default true)
spring.api-docs.enabled=true

# for checking the swagger-ui page on link :  
# http://localhost:8181/swagger-ui/index.html

Добавьте аннотацию swagger на класс контроллера

• 1, откройте файл UserController.java, а затем добавьте аннотацию swagger на каждую конечную точку следующим образом

    @Operation(summary = "Api save data")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
            @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
    })
    @PostMapping(value = "/save")
    public ResponseEntity<Response> save(@RequestBody UserDTO request) {
        return userService.save(request);
    }

    @Operation(summary = "Api update data")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
            @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
    })
    @PutMapping(value = "/update/{id}")
    public ResponseEntity<Response> update(@PathVariable Long id,
                                           @RequestBody UserDTO request) {
        return userService.update(id, request);
    }

    @Operation(summary = "Api delete data")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
            @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
    })
    @DeleteMapping(value = "/delete/{id}")
    public ResponseEntity<Response> delete(@PathVariable Long id) {
        return userService.delete(id);
    }

    @Operation(summary = "Api delete all data")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
            @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
    })
    @DeleteMapping(value = "/delete/all")
    public ResponseEntity<Response> deleteAll() {
        return userService.deleteAll();
    }

    @Operation(summary = "Api get all data")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
            @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
    })

@Operation(summary = "Api find data by id")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Success", content = {@Content(mediaType = "application/json")}),
        @ApiResponse(responseCode = "404", description = "Data not found", content = @Content)
})
@GetMapping("/find/{id}")
public ResponseEntity<Response> findById(@PathVariable Long id) {
    return userService.findById(id);
}

Описания аннотаций:

• Operation используется для описания API конечных точек и будет отображаться в Swagger-UI.
• ApiResponse используется для определения типа ответа и будет отображаться в Swagger-UI

Запустите приложение Springboot

• приложение Springboot и убедитесь, что приложение запущено.

приложение запущено

Протестируйте все Rest API с помощью Swagger UI

• шаг 1, откройте swagger-ui в браузере: http://localhost:8181/swagger-ui/index.html

Домашняя страница Swagger-UI

• шаг 2, нажмите на меню аккордеона на каждой конечной точке, пример конечной точки (/api/user/save)

аккордеонное меню на UserController

• шаг 3, нажмите кнопку try it out, введите json тело пользователя и нажмите кнопку execute

Swagger-UI вводим json тело пользователя для тестирования и выполняем

• тест api сохранить пользователя является успешным, вы можете увидеть ответ

Swagger-UI ответ тестируемого API

Заключение

Наконец, мы уже научились создавать документацию API с помощью Swagger на Springboot, на примере CRUD api.

Полный исходный код здесь