# flash-ext-openapi

OpenAPI 3.0.3 generation + Swagger UI for Flash.

## What it provides

| Route | Description |
|---|---|
| `GET /openapi.json` | OpenAPI spec JSON |
| `GET /openapi.yaml` | OpenAPI spec YAML |
| `GET /openapi/swagger` | Swagger UI |

## Install

```java
FlashApp.create(8080)
    .install(new JacksonExtension())
    .install(new OpenApiExtension("/openapi", "My API", "1.0.0"))
    .scan("com.acme.handlers")
    .startAndBlock();
```

## Operation annotation

```java
@GET("/users/{id}")
@ApiOperation(summary = "Get user", description = "Returns one user", tags = {"users"})
@Parameter(name = "expand", in = ParameterIn.QUERY, type = SchemaType.STRING, examples = {"roles", "permissions"})
@APIResponse(
    responseCode = "200",
    description = "User found",
    content = @Content(contentType = ContentType.JSON, schema = UserDto.class)
)
public final class GetUser extends RequestHandler { ... }
```

## Response patterns

### Single object

```java
@APIResponse(
    responseCode = "200",
    description = "User found",
    content = @Content(contentType = ContentType.JSON, schema = UserDto.class)
)
```

### Array

```java
@APIResponse(
    responseCode = "200",
    description = "Users listed",
    content = @Content(contentType = ContentType.JSON, schema = UserDto.class, array = true)
)
```

### No content

```java
@APIResponse(
    responseCode = "204",
    description = "Deleted",
    content = @Content(contentType = ContentType.NONE)
)
```

### Inferred from handler return type

```java
@APIResponse(
    responseCode = "200",
    content = @Content
)
```

If `content.schema` is omitted, schema is inferred from the handler `handle(...)` return type.
Explicit `content.schema` always wins over inference.

Inference defaults:

- `UserDto` -> object schema for `UserDto`
- `List<UserDto>` / `Set<UserDto>` / `UserDto[]` -> `array` with `items: UserDto`
- `Map<String, UserDto>` -> `object` with `additionalProperties: UserDto`

## DTO schema metadata

```java
@Schema(name = "User", title = "User DTO", description = "Public user", deprecated = false)
public class UserDto {

    @SchemaProperty(title = "ID", required = true, example = "USR-100", enumeration = {"USR-100", "USR-101"})
    public String id;

    @SchemaProperty(hidden = true)
    public String internalDebug;
}
```

Supported field-level exclusion:

- `@Schema(hidden = true)` / `@SchemaProperty(hidden = true)`
- `@JsonIgnore`
- `@JsonIgnoreProperties(...)`
- `transient` / `static`

## OIDC interop

When `flash-ext-oidc` is installed, OpenAPI integrates automatically:

- security scheme under `components.securitySchemes`
- per-operation `security`
- auto responses (class-based handlers):
  - `401 Authentication required`
  - `403` role/scope required messages when applicable

Manual `@APIResponse` for the same status code always wins.

## Notes

- Operations are collected from final boot-time routes for class-based handlers with `@ApiOperation`.
- Documented paths always match runtime paths (including scope namespaces/prefixes/rewrites).
- Route path params are auto-discovered from `/{id}`.
- Parameter annotations are mainly for query/header/cookie enrichment.
- Output responses are sorted by numeric status code.