Przejdź do treści

Dokumentacja API (OpenAPI)

Generujemy z kodu: ./gradlew openApi -> build/openapi/openapi.json. Przykładowy kontroler: PortRESTController (+ PortDTO).

Wersja specyfikacji

Generujemy OpenAPI 3.2.1 (OpenApiGenerator.OPENAPI_VERSION). Od 3.1 schematy to JSON Schema 2020-12, więc w wygenerowanym pliku:

Adnotacja W openapi.json
@Schema(example = 'Gdańsk') "examples": ["Gdańsk"] (example w schematach jest wycofane)
@Schema(nullable = true) "type": ["string", "null"]; dla odwołania do klasy anyOf z null
@Schema(description = ...) na polu typu DTO description obok $ref (w 3.0 było to ignorowane)
pole byte[] "contentMediaType": "application/octet-stream"

Co jest generowane bez adnotacji

Co Skąd
ścieżka, metoda HTTP UrlMappings.groovy; metoda bez mapowania - z static allowedMethods
parametry ścieżki ({id}) zmienne w mapowaniu ($id)
role, wymaganie tokenu @Secured na akcji albo kontrolerze
ciało żądania POST/PUT/PATCH argument akcji będący klasą z logintegra.*, np. def save(PortDTO portDTO)
schemat klasy DTO / command pola klasy (typy, enumy, listy, zagnieżdżone klasy)
grupa (tag) nazwa kontrolera bez Controller

Adnotacje

Paczka io.swagger.v3.oas.annotations (zależność swagger-annotations). Składnia Groovy: tablice w [], klasy bez .class.

Potrzeba Adnotacja Gdzie
podsumowanie, opis @Operation(summary = '...', description = '...') akcja
parametr zapytania / nagłówka (params.x) @Parameter(name = 'x', in = ParameterIn.QUERY, description = '...', schema = @Schema(implementation = Typ)) akcja, można powtarzać
opis parametru ścieżki @Parameter(name = 'id', in = ParameterIn.PATH, description = '...') akcja
ciało żądania, gdy akcja czyta request.JSON @ApiRequestBody(required = true, content = @Content(schema = @Schema(implementation = Dto))) akcja
odpowiedź @ApiResponse(responseCode = '200', description = '...', content = @Content(...)) akcja, można powtarzać
odpowiedź opakowana {port: {...}} @Content(schemaProperties = [@SchemaProperty(name = 'port', schema = @Schema(implementation = PortDTO))]) w @ApiResponse
lista {ports: [...]} @SchemaProperty(name = 'ports', array = @ArraySchema(schema = @Schema(implementation = PortDTO))) w @ApiResponse
błąd {error: '...'} @Content(schema = @Schema(ref = 'Error')) w @ApiResponse
opis pola DTO, przykład, wymagane @Schema(description = '...', example = '...', requiredMode = Schema.RequiredMode.REQUIRED) pole DTO
dozwolone wartości pola String @Schema(allowableValues = ['AIR', 'SEA']) pole DTO
nazwa i opis grupy @Tag(name = '...', description = '...') kontroler
ukrycie (testy, mocki) @Hidden akcja albo kontroler
wycofany endpoint @Deprecated akcja

Przykład

@Tag(name = 'Porty', description = 'Porty lotnicze i morskie (słownik)')
class PortRESTController extends RestfulController {

    @Secured(['IS_AUTHENTICATED_FULLY'])
    @Operation(summary = 'Lista aktywnych portów')
    @Parameter(name = 'portType', in = ParameterIn.QUERY, description = 'Filtr typu portu',
            schema = @Schema(implementation = PortType))
    @ApiResponse(responseCode = '200', description = 'Porty', content = @Content(schemaProperties = [
            @SchemaProperty(name = 'ports', array = @ArraySchema(schema = @Schema(implementation = PortDTO)))]))
    @ApiResponse(responseCode = '400', content = @Content(schema = @Schema(ref = 'Error')))
    def index() { ... }

    @Secured(['ROLE_SUPER_USER'])
    @Operation(summary = 'Utworzenie portu')
    @ApiResponse(responseCode = '200', content = @Content(schemaProperties = [
            @SchemaProperty(name = 'port', schema = @Schema(implementation = PortDTO))]))
    def save(PortDTO portDTO) { ... }
}

Zasady

  • Opisy po polsku, jak reszta kodu.
  • @Hidden na kontrolerach testowych i mockach (AdfsTestREST, TestREST).
  • Po zmianie: ./gradlew openApi - OpenApiSpec sprawdza m.in., czy każde odwołanie do schematu ($ref) istnieje i czy mapowania wskazują istniejące kontrolery

Ostatnia zmiana: 2026-09-28 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e