Add automated OpenAPI specification generation for hosted documentation #208
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
I've been testing it out locally. So far I found a couple of things: warnings in the logs: also this link: http://localhost:8000/mcpd/api/openapi.yaml returns a 404 - not found
|
Extract route registration logic into internal/api/routes.go with RegisterRoutes function. This ensures daemon and docs generation use identical route definitions, maintaining 1:1 mapping between code and documentation. Introduces api.APIVersion constant as single source of truth for API version used in OpenAPI spec and URL paths. The RegisterRoutes function extracts this version from the router's OpenAPI spec and returns the path prefix for logging. All parameters require non-nil values with defensive checks using reflection to prevent panics from interface nil checks. Updates internal/daemon/api_server.go to use RegisterRoutes and api.APIVersion constant, removing duplicate route registration code.
Introduce tools/docsgen/api/openapi.go for programmatic OpenAPI spec export. The tool uses api.RegisterRoutes with stub implementations of contracts to generate the spec without running the daemon. Output is written to docs/api/openapi.yaml which is excluded from version control via .gitignore, matching the pattern used for CLI docs in docs/commands/. This ensures a 1:1 mapping between the actual API code and the published OpenAPI specification, automatically generated during documentation deployment.
Add error handling for encoder.Close() call in updateMkDocsNav function to satisfy errcheck linter. The encoder must be properly closed to flush any buffered output before writing the final YAML to the file.
Update Makefile targets to reflect new tools structure where each standalone tool lives in its own directory (cmds/, nav/, api/) rather than sharing tools/docsgen/cli/. Add docs-api target to generate OpenAPI specification. Configure golangci-lint to include build tags for all docsgen tools and validate_registry, ensuring proper linting of build-tagged files that were previously excluded from analysis.
Add OpenAPI spec generation step to deploy-docs workflow between CLI docs generation and navigation updates. This ensures the spec is generated fresh on every docs deployment. Update mkdocs.yaml to include API Reference section with link to the generated OpenAPI specification file. Update GitHub Actions versions across all workflows to latest pinned releases for actions/checkout, actions/setup-go, and astral-sh/setup-uv.
* make docs includes building OpenAPI too
peteski22
force-pushed
the
peteski22/api/openapi-docs-generation
branch
from
c6cdf96 to
651c157
Compare
🤦🏼 whoops, I forgot to include the |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds programmatic OpenAPI YAML export to maintain 1:1 mapping between API code and hosted documentation.
Changes
internal/api/RegisterRoutes()as single source of truthtools/docsgen/api/tool that generates OpenAPI spec without running daemonmake docs-apiin deploy-docs workflowapi.APIVersionconstant (v1) to prevent version mismatches between daemon and docsBenefits
/openapi.yamlduring runtime AND in static docs (https://.../mcpd/api/openapi.yaml)Side improvements
Local testing
The check out the docs 😄