MicroProfile OpenAPI

# CLAUDE.md — MicroProfile OpenAPI

## Setup

- Add the MP-OpenAPI implementation: SmallRye OpenAPI in Quarkus, Open Liberty's bundled implementation, etc.
- Spec is exposed at `/openapi`. Many runtimes also expose Swagger UI at `/openapi/ui` or similar.
- Most documentation generates from JAX-RS + Bean Validation. Annotate only when the inferred docs are wrong or insufficient.

## Application metadata

```java
@OpenAPIDefinition(
    info = @Info(
        title = "My API",
        version = "1.0.0",
        contact = @Contact(name = "Team", email = "team@example.com"),
        license = @License(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0")
    ),
    servers = {
        @Server(url = "https://api.example.com", description = "Production"),
        @Server(url = "https://staging.example.com", description = "Staging")
    }
)
@ApplicationPath("/")
public class App extends Application {}
```

## Operation annotations

- `@Operation(summary = "...", description = "...")` on resource methods.
- `@APIResponse(responseCode = "200", description = "...", content = @Content(...))` for documented responses.
- `@APIResponses` to group multiple. Always document at least the success status and the most common error.
- `@Parameter(description = "...", example = "abc-123")` on path/query params for clarity.

## Schemas

- DTOs are auto-discovered from JAX-RS method signatures.
- Customize with `@Schema` on classes or fields:
  ```java
  @Schema(description = "Order item with quantity and product reference")
  record OrderItem(
      @Schema(required = true, example = "prod_123") String productId,
      @Schema(minimum = "1", maximum = "100", example = "1") int quantity
  ) {}
  ```
- Bean Validation annotations (`@NotBlank`, `@Size`) flow through automatically — don't duplicate as `@Schema(required = true)` everywhere.

## Tags

- Group endpoints with `@Tag(name = "Users", description = "User management")`.
- One tag per resource class — keeps the rendered UI navigable.
- Order tags via `@OpenAPIDefinition(tags = { @Tag(name = "..."), ... })` for consistent display.

## Security schemes

```java
@SecurityScheme(
    securitySchemeName = "bearer",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
@OpenAPIDefinition(security = @SecurityRequirement(name = "bearer"))
```

- Apply per operation with `@SecurityRequirement` if the global default doesn't fit.
- Public endpoints: `@SecurityRequirements` (empty) to override.

## Examples

- Concrete examples make the spec actually usable for client developers:
  ```java
  @APIResponse(responseCode = "200", content = @Content(
      schema = @Schema(implementation = User.class),
      examples = @ExampleObject(name = "user", value = "{\"id\":\"1\",\"email\":\"a@b\"}")
  ))
  ```

## Workflow

- Generate the spec at build time (`mvn package` produces `META-INF/openapi.yaml`).
- Diff the spec in CI to catch unintended API changes.
- Publish to a developer portal (Swagger Hub, Stoplight, your own).

## Don't

- Don't write the OpenAPI spec by hand alongside annotations. Pick one source of truth.
- Don't expose `/openapi` to the public internet without auth if your spec leaks internal details.
- Don't use `@Schema(implementation = Object.class)` to escape strict typing — fix the type.
- Don't ship a spec that doesn't match the implementation. Validate in tests.