clientgen: Fix missing documentation in OpenAPI schema generation #2029
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
Fixes missing documentation in OpenAPI schema generation for both field-level and struct-level comments.
Problems Fixed
1. Field documentation lost with schema references
When a struct field with documentation references another struct type, the field documentation was lost because
val.Valueisnilfor schema references.Before:
After:
2. Missing struct-level documentation
Struct declarations with documentation comments weren't including that documentation in the generated OpenAPI component schemas.
Before:
After:
Technical Details
Field Documentation Fix (lines 75-87)
Uses the
allOfpattern recommended for OpenAPI 3.0 to add descriptions to$ref. This is the official workaround for OpenAPI 3.0's limitation where sibling properties to$refare ignored.Struct Documentation Fix (lines 288-302)
When generating named schema types, include the declaration's documentation from
g.md.Decls[typ.Id].Docin the schema's title and description fields.Testing
DocumentedUser,DocumentedOrder) to test dataExample Output
The generated OpenAPI now includes comprehensive documentation:
{ "components": { "schemas": { "svc.DocumentedUser": { "title": "DocumentedUser represents a user in the system with profile information", "properties": { "name": {"type": "string"}, "email": {"type": "string"} } } } }, "paths": { "/svc.CreateDocumentedOrder": { "requestBody": { "schema": { "properties": { "customer": { "allOf": [{"$ref": "#/components/schemas/svc.DocumentedUser"}], "description": "Customer who placed this order (different from shipping recipient)" } } } } } } }This resolves the issue where OpenAPI client generators and documentation tools couldn't access important contextual information about API fields and schemas.
I ran this against our own encore project and it works as expected.