Export an OpenAPI specification artefact

[Lakes41]

Difficulty: Hard

Type: Documentation

Summary

Generate and publish an OpenAPI JSON artefact for the access API so SDKs, integrations, and contributors can rely on a stable machine-readable API contract.

Current Behaviour

Fastify route schemas may power Swagger UI at runtime, but there is no clearly versioned OpenAPI artefact committed or produced in CI.

Expected Behaviour

The repository should produce an OpenAPI JSON file that can be validated in CI and used by SDK tooling.

Suggested Implementation

Add a script that builds the Fastify app, serialises the OpenAPI specification, and writes it to docs/openapi.json or a generated artefact directory. Add CI validation to catch schema generation failures.

Files or Areas Likely Affected

• apps/access-api/src/app.ts
• apps/access-api/src/routes.ts
• apps/access-api/package.json
• docs/openapi.json
• .github/workflows/

Acceptance Criteria

• A command generates the OpenAPI JSON spec
• The generated spec includes all public API routes
• The generated spec includes request and response schemas
• CI verifies the spec can be generated
• README links to the generated specification
• Contributors know how to update the spec when routes change

Additional Notes

This should complement route schemas and sdk-lite contract tests.

[Glam26]

I'd like to work on this issue.

I've implemented OpenAPI generation and API contract workflows in several production projects, including Fastify-based services where route schemas were used as the single source of truth for documentation, SDK generation, and integration testing. I've also set up CI validation to ensure API specifications remain accurate as routes evolve.

For this task, I'll add a reproducible OpenAPI generation command, ensure all public routes and request/response schemas are captured in the generated specification, and integrate validation into CI so schema-generation failures are caught before merge. I'll also update the documentation with a clear workflow for regenerating and reviewing the spec, helping maintain a reliable contract between the Access API, SDK consumers, and external integrations.

[Glam26]

I'd like to work on this issue.

I've implemented OpenAPI generation and API contract workflows in several production projects, including Fastify-based services where route schemas were used as the single source of truth for documentation, SDK generation, and integration testing. I've also set up CI validation to ensure API specifications remain accurate as routes evolve.

For this task, I'll add a reproducible OpenAPI generation command, ensure all public routes and request/response schemas are captured in the generated specification, and integrate validation into CI so schema-generation failures are caught before merge. I'll also update the documentation with a clear workflow for regenerating and reviewing the spec, helping maintain a reliable contract between the Access API, SDK consumers, and external integrations.

[felladaniel36-hash]

​Hi maintainer, I would love to work on this issue. I can get started on it right away. Could you please assign it to me?

[grantfox-oss]

🦊 GrantFox — @Glam26 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #49)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Glam26's PR #69 was approved and merged by @Lakes41.

🏆 @Glam26: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (751 total points). Track your full progress on GrantFox.

👏 Great work, @Glam26! Keep contributing to Adamantine-guild.