grails - 如何在Grails 4上使用批注创建OpenAPI(Swagger)文档

Question

我们正在为现有的Grails 4应用程序创建API文档。我们在理解如何使用Swagger注释方面遇到困难。

让我们假设以下 Controller :

class IntegratorController {

    def maintenanceService

    def saveMaintenance() {
        def message = 'success'
        def status = '200'

        try {
            def maintenanceJson = request.JSON.maintenances
            def ret=maintenanceService.processMaintenanceJSON(maintenanceJson)

        } catch (Exception e) {
            log.error("Error to process restricions", e)
            message = 'error : ${e.getMessage()}'
            status = '500'
        }

        def result = ['message':message]
        render(status: status, contentType: "application/json", text: result as JSON)
    }

}

该 Controller 希望您像以下示例一样发送请求JSON:

{ "job":42,
  "maintenances": [
    {"idPort":42, "idMaintenance":42, "shipName":"myship01", "obs":"asap"},
    {"idPort":43, "idMaintenance":43, "shipName":"myship02", "obs":"asap"}]}

一个基本的注释将是这样的:

@Controller("/")
class IntegratorController {

    def maintenanceService

    @Post(uri="/saveMaintenance", produces = MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    @Operation(summary = "Create one or more ship maintenance")
    @ApiResponse(responseCode = "500", description = "If internal service throws an Exception")
    def saveMaintenance() {
        def message = 'success'
        def status = '200'

        try {
            def maintenanceJson = request.JSON.maintenances
            def savedMaintenances=maintenanceService.processMaintenanceJSON(maintenanceJson)

        } catch (Exception e) {
            log.error("Error to process restricions", e)
            message = 'error : ${e.getMessage()}'
            status = '500'
        }

        def result = ['message':message]
        render(status: status, contentType: "application/json", text: result as JSON)
    }
}

在何处以及如何注释在post操作中发送的请求JSON？

谢谢!

Answer 1

请求对象由Grails“作用域”。因此，您需要使用@RequestBody批注来声明它在方法声明之外。您还需要创建类来描述它是什么，因为JSON反序列化是松散类型的。

这是一个例子:

    @Post(uri="/saveMaintenance", produces = MediaType.APPLICATION_JSON)
    @Operation(summary = "Summary here",
            description = "Description here",
            requestBody = @RequestBody(description = "Inside Operation"), tags = ["IntegratorWebController"])
    @RequestBody(description = "Description here", required = true,
            content = @Content(schema = @Schema(implementation = YourRequestDAO.class, anyOf = [YourRequestDAO.class, YourRequestDAODependency.class])))
    @ApiResponses(value=[
            @ApiResponse(responseCode="200", description = "Return status=OK in success", content = @Content(mediaType = "application/json", schema = @Schema(implementation = YourResponseDAO.class))),
            @ApiResponse(responseCode="404", description = "Return status=BAD_REQUEST if you mess up", content = @Content(mediaType = "application/json", schema = @Schema(implementation = YourResponseDAO.class)))])
    def saveOrUpdateActivity(){
(...)