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

Введение

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

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

Требования

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