docs: add OpenAPI documentation for OIDC endpoints

[mairas]

Summary

• Add OpenAPI 3.0 documentation for the OIDC configuration endpoints
• New schemas: OIDCConfigResponse, OIDCConfigRequest, OIDCTestRequest, OIDCTestResponse, OIDCPermission
• Documented endpoints:
  • GET /security/oidc - Retrieve OIDC configuration (secrets redacted)
  • PUT /security/oidc - Update OIDC configuration
  • POST /security/oidc/test - Test OIDC provider connectivity

This completes the Phase 4 (Admin UI Configuration) by adding the missing API documentation.

Test plan

• JSON syntax validates correctly
• TypeScript build passes

Closes #5

🤖 Generated with Claude Code

[mairas]

PR Review: docs: add OpenAPI documentation for OIDC endpoints

Summary

This PR adds OpenAPI 3.0 documentation for the OIDC configuration endpoints, completing part of Phase 4 (Admin UI Configuration) from issue #5.

CI Status ❌

The label check is failing because the PR is missing a required label. Since this is a documentation change, please add the doc label.

Documentation Quality ✅

The OpenAPI documentation is well-structured and comprehensive:

Schemas defined:

• OIDCPermission - enum for permission levels (readonly, readwrite, admin)
• OIDCConfigResponse - response for GET endpoint with all configuration fields
• OIDCConfigRequest - request body for PUT endpoint
• OIDCTestRequest / OIDCTestResponse - for the connection test endpoint

Endpoints documented:

Endpoint	Method	Purpose
/security/oidc	GET	Retrieve OIDC config (secrets redacted)
/security/oidc	PUT	Update OIDC config
/security/oidc/test	POST	Test OIDC provider connectivity

Observations

1. Security handling: The clientSecret field in OIDCConfigResponse is documented as "Always empty (redacted for security)" with a separate clientSecretSet boolean indicator. This is a good security practice.

2. Flexible input: The adminGroups and readwriteGroups fields in OIDCConfigRequest accept both comma-separated strings and arrays using oneOf. This provides good flexibility for API consumers.

3. Error responses: Each endpoint documents appropriate error responses (400, 401, 500, 502 where applicable).

4. Environment variable overrides: The envOverrides field in OIDCConfigResponse documents which fields are locked via environment variables - useful for admin UI to show read-only states.

Minor Notes

• The documentation references /security/oidc paths while the issue mentions /signalk/v1/security/oidc. The base path is likely defined elsewhere in the OpenAPI spec, so this is probably correct.

Verdict

Documentation looks complete and well-organized. Just needs the doc label to pass CI.