# 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
