docs: add OpenAPI specs for auth service public endpoints

[goshacodes]

Adds OpenAPI 3.1 specifications for the auth service's public OAuth/OIDC endpoints, one spec per endpoint (grouped by path where GET/POST share a route):

• authorize.yaml — GET/POST /authorize
• par.yaml — POST /par
• token.yaml — POST /token
• introspect.yaml — POST /introspect
• revoke.yaml — POST /revoke
• userinfo.yaml — GET/POST /userinfo
• logout.yaml — GET/POST /logout
• jwks.yaml — GET /.well-known/jwks.json
• metadata.yaml — GET /.well-known/oauth-authorization-server and /.well-known/openid-configuration

Each spec was derived directly from the corresponding controller, request parser, and error model, and includes request/response schemas, error variants, and security schemes. Validated with redocly/cli (no errors).

These specs are consumed by the versola-website docs site (companion PR), which renders one documentation page per endpoint from them.

---

Pull Request opened by Augment Code | View session

[augmentcode]

🤖 Augment PR Summary

Summary: This PR adds standalone OpenAPI 3.1 specifications for the auth service's public OAuth/OIDC surface.

Changes:

• Documents the authorization endpoint for both query and form submissions.
• Documents PAR and the authorization request/response and error contracts.
• Adds token, introspection, and revocation endpoint definitions.
• Adds UserInfo and RP-initiated logout definitions for both supported methods.
• Adds JWKS and OAuth/OIDC discovery metadata endpoint specifications.
• Defines shared request schemas, response payloads, headers, cookies, and security schemes per file.

Technical Notes: The specifications are intended for consumption by the companion documentation site, with endpoint-specific files rather than a combined document.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 6 suggestions posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

AuthorizeRequestParser.resolvePushedRequest requires only the outer client_id and then replaces the rest of the payload, so a valid /authorize?client_id=...&request_uri=... request has no redirect_uri. Marking these parameters required makes the documented GET and POST contracts reject the PAR flow this file describes. Other locations where this applies: auth/open-api/authorize.yaml:109, auth/open-api/authorize.yaml:121, auth/open-api/authorize.yaml:132, auth/open-api/authorize.yaml:305.

Severity: medium

Other Locations

• auth/open-api/authorize.yaml:109
• auth/open-api/authorize.yaml:121
• auth/open-api/authorize.yaml:132
• auth/open-api/authorize.yaml:305

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

The parser splits prompt on spaces and accepts combinations such as login consent (rejecting only a combination containing none), but this scalar enum makes every such documented space-delimited combination invalid. This causes validators and generated docs to reject valid authorization requests.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

extractCredentials reads client_secret_post exclusively from the parsed form; it never reads a client_secret cookie. Declaring this as a cookie apiKey causes OpenAPI tooling to send the secret in a location the endpoint ignores, despite the body schema description. Other locations where this applies: auth/open-api/par.yaml:72, auth/open-api/revoke.yaml:55, auth/open-api/token.yaml:85.

Severity: medium

Other Locations

• auth/open-api/par.yaml:72
• auth/open-api/revoke.yaml:55
• auth/open-api/token.yaml:85

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

When JWT deserialization fails, IntrospectionController returns the inactive 200 response directly without either cache header. Therefore this response contract promises Cache-Control: no-store and Pragma: no-cache for an ordinary documented outcome that does not actually include them.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

performLogout delegates to renderLogout, which always produces a 200 HTML signed-out page and embeds the post-logout URI for client-side navigation; it never sets Location or returns 303. The advertised redirect response is therefore unreachable for successful logout requests. Other locations where this applies: auth/open-api/logout.yaml:77.

Severity: medium

Other Locations

• auth/open-api/logout.yaml:77

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

The successful path in TokenEndpointController creates Response.json(response.toJson) without adding Cache-Control, while only its error path adds no-store. This contract consequently guarantees a sensitive token response header that clients do not receive.

Severity: high

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}