Automate docs/openapi.json#1190
Merged
jealous merged 3 commits intoMar 10, 2026
Merged
Conversation
Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves API documentation automation by adding FastAPI route tags for clearer grouping in generated OpenAPI output, enhancing the OpenAPI generation script, and adding CI workflows to keep both the OSS and Platform OpenAPI specs up to date for the public docs site.
Changes:
- Add explicit
tags=[...]metadata across API v2 routes to produce categorized OpenAPI output. - Replace/upgrade the OpenAPI generation script to normalize
info, clean/disambiguateoperationIds, sort paths, and inject examples. - Add GitHub Actions workflows to auto-regenerate
docs/openapi.jsonand to periodically syncdocs/platform.openapi.json.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/server/src/memmachine_server/server/api_v2/router.py | Adds per-endpoint tags to improve OpenAPI grouping; includes System tag endpoints. |
| packages/server/src/memmachine_server/server/api_v2/config_router.py | Moves away from router-level tags to per-endpoint tags to support mixed grouping (Configuration vs Resources). |
| docs/tools/generate_unified_openapi.py | Removes an older unified OpenAPI generator script. |
| docs/tools/generate_openapi.py | Expands generation logic (version normalization, operationId cleanup/disambiguation, tag metadata, path ordering, examples). |
| docs/openapi.json | Updates committed OpenAPI output to the newly generated, tagged, and enriched spec. |
| .github/workflows/generate-openapi.yml | Adds automation to regenerate docs/openapi.json on relevant main changes and open a PR if it differs. |
| .github/workflows/sync-platform-openapi.yml | Adds automation to download and PR-update docs/platform.openapi.json on schedule/release. |
| .github/workflows/docs-checks.yml | Validates platform.openapi.json (if present) with Mintlify in CI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>
SarahScargall
approved these changes
Mar 10, 2026
SarahScargall
left a comment
SarahScargall
left a comment
Contributor
There was a problem hiding this comment.
LGTM - we can use this immediately with the updates to PR #1200.
jealous
approved these changes
Mar 10, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Purpose of the change
This change adds metadata tags (categories) to the FastAPI server endpoints. These tags are used to auto generate the
openapi.jsonthat is required for the public documentation on docs.memmachine.ai. This PR also includes automation to pull the latest MemMachine Platform API (openapi.json) and store it asdocs/platform.openapi.jsonthat is also displayed in the public docs.Description
As stated above. This solves the problem of humans needing to manually generate the
openapi.jsoneach time the APIs are modified, or at release time.It's critical to organize the API endpoints for developer friendly organization and findability.
Fixes/Closes
Fixes #317
Type of change
How Has This Been Tested?
Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.
Test Results: [Attach logs, screenshots, or relevant output]
The scripts have been tested and the resulting
openapi.jsonandplatform.openapi.jsontested and validated in an offline Mintlify dev environment.Checklist
Maintainer Checklist
Screenshots/Gifs
N/A
Further comments
N/A