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.
@Hiddenna kontrolerach testowych i mockach (AdfsTestREST,TestREST).- Po zmianie:
./gradlew openApi-OpenApiSpecsprawdza 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