Как использовать аннотации для создания документации OpenAPI (Swagger) на Grails 4 - PullRequest
Новая
       9

Как использовать аннотации для создания документации OpenAPI (Swagger) на Grails 4

1 голос
/ 07 апреля 2020

Мы создаем документацию по API для существующего приложения Grails 4. У нас возникают трудности в понимании того, как использовать аннотации Swagger.

Предположим, что следующий контроллер: 

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)
    }

}

Этот контроллер ожидает, что вы отправите запрос JSON, как в этом примере: 

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

Основная аннотация c будет такой: 

@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)
    }
}

Где и как аннотировать запрос JSON, отправленный в почтовой операции?

Спасибо !

Ответы [ 2 ]

1 голос
/ 08 апреля 2020

Объект запроса "ограничен" 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(){
(...)
0 голосов
/ 08 апреля 2020

Ну, Swagger и OpenAPI - это «схемы», которые предварительно загружаются во время выполнения для построения структуры вызовов; GraphQL также имеет схему для загрузки структуры вызовов.

Я сделал здесь видео, чтобы помочь вам понять, как это работает: https://youtu.be/AJJVnwULbbc

Grails делал это до 4.0 с помощью плагинов, таких как «swagger plugin» или с плагином BeAPI (который я поддерживаю).

Я не вижу поддерживаемый плагин в 4.0, поэтому я не вижу, как они делаем это сейчас.

...