feat: internal_docs build tag keeps a method out of every other build - #90
Merged
Merged
Conversation
A method tagged internal_docs is generated only by a build run with build_tag=internal_docs. Until now the only way to keep a method out of a spec was the public_docs allow-list, which does nothing for a service whose public spec is built without a build tag (unifydental, unifyvet, unifyaesthetics: every method appears). This gives such a service a per-method opt-out: the endpoint stays in the API, the Go code and the gateway, and out of the published documentation. Existing behaviour is unchanged for public_docs, postman and untagged builds of methods that do not carry the tag. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ions A tag for a service none of whose methods made it into the build put the service's name and description into that spec anyway — which is exactly what an internal_docs-only service must not leak into a public spec. It also drops the empty tag a public_docs build emitted for a service with no public methods (customparamsexclude golden updated). Fixture gains an internal-only service to pin this. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Collaborator
Author
|
Added a second commit: a service's tag is now emitted only when the build carries at least one of its operations. Found while wiring this into schema — an internal-only service still leaked its name and description into the public spec as an empty tag. Same rule also drops the empty tag a public_docs build produced for a service with no public methods (the customparamsexclude golden changed for that reason). Fixture gains an internal-only service to pin it. |
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The JSON-naming test does not apply the fixture’s build tag, leaving internal-operation inclusion untested.
Get a fresh assessment by requesting another Copilot review.
Review effort: Balanced
Findings: 1
What changed in this PR
Adds internal_docs filtering so tagged methods appear only in internal documentation builds.
Changes:
- Implements and documents
internal_docs. - Omits tags for services with no generated operations.
- Adds golden fixtures for tagged and untagged builds.
Required change: TestOpenAPIJSONNaming must pass tt.buildTag; then regenerate the included JSON golden to contain the internal operations.
| File | Description |
|---|---|
README.md |
Documents build-tag semantics. |
plugin_test.go |
Registers internal-doc fixtures; JSON build-tag coverage needs correction. |
generator/openapi-v3.go |
Implements filtering and empty-service tag handling. |
examples/tests/internaldocsincluded/openapi.yaml |
Internal-build proto-naming golden. |
examples/tests/internaldocsincluded/openapi_json.yaml |
Internal-build JSON-naming golden requiring regeneration. |
examples/tests/internaldocsincluded/message.proto |
Defines the internal-build fixture. |
examples/tests/internaldocs/openapi.yaml |
Untagged proto-naming golden. |
examples/tests/internaldocs/openapi_json.yaml |
Untagged JSON-naming golden. |
examples/tests/internaldocs/message.proto |
Defines the untagged-build fixture. |
examples/tests/customparamsexclude/openapi.yaml |
Updates empty-service output. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Tagging a service only when one of its methods was generated also changed public_docs (and other tagged) builds: the tag count drives info.title and info.description, so customparamsexclude lost its "Messaging API" title. Go back to tagging every service with annotated methods, except one whose annotated methods were all left out by the internal_docs filter. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
TestOpenAPIJSONNaming ran every fixture untagged, so the JSON goldens of the build-tag fixtures (customparams*, internaldocsincluded) recorded an untagged build. Pass tt.buildTag as the protobuf-naming test does and regenerate them; each now matches its openapi.yaml apart from naming and version. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
jnewmano
enabled auto-merge (squash)
September 24, 2026 03:09
jnewmano
disabled auto-merge
September 24, 2026 03:09
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.
Summary
Adds a third build tag with meaning,
internal_docs: a method that carries it in(openapi.method_params).build_tagsis generated only by a build run withbuild_tag=internal_docs, and left out of every other build — including an untagged one.Why:
public_docsis an allow-list, so it does nothing for a service whose public spec is built with no build tag (schema'sunifydental,unifyvet,unifyaesthetics— every method appears in the README). This is the per-method opt-out for such a service: the endpoint stays in the API, the Go code and the gateway, and out of the published documentation. First use: an internal change-feed endpoint inunifydental(schema PR to follow, with abuild_tag=internal_docsrun for itskollainternalspec).Nothing changes for
public_docs,postman, or untagged builds of methods that don't carry the tag.Test plan
examples/tests/internaldocs(untagged build → only the public method) andexamples/tests/internaldocsincluded(build_tag=internal_docs→ both methods), in both the proto-naming and JSON-naming test tablesgo test ./...green locally with protoc 30.2Release as v0.0.28 after merge; schema pins the generator by version in
go.modand.devcontainer/local-feature/install.sh.🤖 Generated with Claude Code