mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-11-03 14:35:32 +08:00
81 lines
5.2 KiB
Markdown
81 lines
5.2 KiB
Markdown
# OpenAPI / Swagger Guide
|
|
|
|
The MateClaw backend integrates [SpringDoc OpenAPI](https://springdoc.org/) (`springdoc-openapi-starter-webmvc-ui`), which auto-generates an OpenAPI 3 document from every `@RestController` and serves an interactive debugging UI. This page covers how to access and use it.
|
|
|
|
> This is the **machine-readable** doc entry point. For the human-readable endpoint details, conventions, and the full route inventory, see the [API Reference](./api.md). Relationship: Swagger = the auto-generated, machine-readable contract from source annotations; `api.md` = flagship endpoint walkthroughs + shared conventions.
|
|
|
|
## URLs
|
|
|
|
After deploying the backend, relative to the server address (default local port `18088`):
|
|
|
|
| URL | Purpose |
|
|
|---|---|
|
|
| `/swagger-ui.html` | Swagger UI — browse + debug (Authorize, Try it out) |
|
|
| `/v3/api-docs` | OpenAPI 3 JSON (import into Postman / Apifox / Insomnia) |
|
|
| `/v3/api-docs.yaml` | OpenAPI 3 YAML (download, commit, or import) |
|
|
|
|
Local examples:
|
|
|
|
```bash
|
|
# Open in a browser
|
|
open http://localhost:18088/swagger-ui.html
|
|
|
|
# Download the YAML
|
|
curl http://localhost:18088/v3/api-docs.yaml -o mateclaw-openapi.yaml
|
|
```
|
|
|
|
## Authentication (Authorize)
|
|
|
|
Use the **Authorize** button at the top right. In the `bearerAuth` field, paste a token **without** the `Bearer ` prefix (the UI adds it automatically):
|
|
|
|
- **JWT**: the `token` field returned by `POST /api/v1/auth/login` (starts with `eyJ...`).
|
|
- **Personal Access Token**: a `mc_...` token created via `POST /api/v1/auth/tokens`.
|
|
|
|
Both go through the standard `Authorization: Bearer <token>` header; the backend `JwtAuthFilter` dispatches by prefix (JWT → JWT verification, `mc_` → PAT verification). Once authorized, protected `@RequireWorkspaceRole` / `@RequireGlobalAdmin` endpoints can be called directly via Try it out.
|
|
|
|
> Debugging SSE streaming endpoints (`/chat/stream`, etc.) in Swagger UI is limited — the UI buffers `text/event-stream` responses. For real SSE integration, follow the [API Reference](./api.md) and use `curl -N` or a `fetch()` streaming reader.
|
|
|
|
## Endpoint coverage
|
|
|
|
SpringDoc auto-scans every `@RestController`. About 85% of controllers already carry `@Tag` (grouping) and `@Operation(summary)` (method summary), so the UI's grouping and endpoint descriptions are largely complete.
|
|
|
|
**Annotation enhancements not yet done** (out of scope for this pass, left for later):
|
|
|
|
- No `@Parameter` descriptions, `@ApiResponse` error codes, or request-body `@Schema` — for field-level docs, defer to the human-readable `api.md` walkthroughs.
|
|
- Public endpoints (login, SSE, etc.) are not individually opted out with `@SecurityRequirements({})`, so they show a lock icon in Swagger even though `SecurityConfig` already permits them — actual calls are unaffected.
|
|
|
|
## Configuration
|
|
|
|
Global OpenAPI metadata (title, description, version, server URL) is driven by the `OpenApiConfig` bean and overridable via `mateclaw.openapi.*` in `application.yml`:
|
|
|
|
```yaml
|
|
mateclaw:
|
|
openapi:
|
|
title: ${MATECLAW_OPENAPI_TITLE:MateClaw REST API}
|
|
version: ${MATECLAW_OPENAPI_VERSION:1.0}
|
|
server-url: ${MATECLAW_OPENAPI_SERVER_URL:} # empty → derived from request host
|
|
description: ${MATECLAW_OPENAPI_DESCRIPTION:} # empty → built-in default
|
|
expose-ui: ${MATECLAW_OPENAPI_EXPOSE_UI:true} # whether the Swagger/OpenAPI paths are public, see the security section below
|
|
```
|
|
|
|
When `server-url` is empty, SpringDoc derives it from the request host so "Try it out" hits the right address; for fixed production URLs (e.g. behind a reverse proxy), set `MATECLAW_OPENAPI_SERVER_URL=https://mate.example.com`.
|
|
|
|
## 🔒 Access control: Swagger is locked down by default in production
|
|
|
|
Access to the Swagger UI / OpenAPI document paths (`/swagger-ui*`, `/v3/api-docs*`, `/webjars/**`) is controlled by the `mateclaw.openapi.expose-ui` flag and enforced explicitly in `SecurityConfig.filterChain` (no longer relying on the `.anyRequest().permitAll()` fallthrough):
|
|
|
|
| `expose-ui` | Behavior | Default profile |
|
|
|---|---|---|
|
|
| `true` | Publicly accessible — anyone can browse the full endpoint surface (incl. request/response schemas) without login | Local / default profile (H2, desktop) |
|
|
| `false` | Requires a global admin (`ROLE_ADMIN`); anonymous → 401, non-admin → 403 | Production database profiles (`mysql` / `kingbase` / `postgres`) |
|
|
|
|
- Local dev: defaults to `true`, so `http://localhost:18088/swagger-ui.html` is reachable directly.
|
|
- Public production: defaults to `false` (locked down). To temporarily open it on an internal/staging host, set `MATECLAW_OPENAPI_EXPOSE_UI=true`.
|
|
- Note: once locked, opening `/swagger-ui.html` in a browser won't automatically carry the SPA's JWT (the token lives in localStorage, not a cookie), so even an admin cannot open it from the browser directly. To debug, either set `expose-ui=true` temporarily, or fetch `/v3/api-docs` with a client that sends the `Authorization` header.
|
|
- The access rule lives only in `SecurityConfig`, not `OpenApiConfig`.
|
|
|
|
## See also
|
|
|
|
- [API Reference (human-readable)](./api.md) — flagship endpoint walkthroughs + conventions + full route inventory
|
|
- [WebChat integration guide](./webchat.md) — external-site HTTP / SSE integration (incl. the SSE event protocol)
|