Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@twindebank
Copy link
Contributor

@twindebank twindebank commented Aug 7, 2025

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.Value is nil for schema references.

Before:

customer:
  $ref: "#/components/schemas/User"
  # Field documentation was lost

After:

customer:
  description: "Customer who placed the order (not the same as delivery recipient)"
  allOf:
    - $ref: "#/components/schemas/User"

2. Missing struct-level documentation

Struct declarations with documentation comments weren't including that documentation in the generated OpenAPI component schemas.

Before:

"svc.User": {
  "type": "object",
  "properties": {...}
  # Missing title/description from struct docs
}

After:

"svc.DocumentedUser": {
  "type": "object", 
  "title": "DocumentedUser represents a user in the system with profile information",
  "properties": {...}
}

Technical Details

Field Documentation Fix (lines 75-87)

Uses the allOf pattern 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 $ref are ignored.

Struct Documentation Fix (lines 288-302)

When generating named schema types, include the declaration's documentation from g.md.Decls[typ.Id].Doc in the schema's title and description fields.

Testing

  • Added documented struct types (DocumentedUser, DocumentedOrder) to test data
  • Updated all expected test outputs (OpenAPI, TypeScript, JavaScript, Go)
  • Verified both fixes work together in generated specs
  • All existing tests pass

Example 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.

Fixes two issues with missing documentation in generated OpenAPI specs:

1. Field documentation lost with schema references: When struct fields
   with documentation reference other struct types, the field docs were
   lost because val.Value is nil for schema references.

2. Missing struct-level documentation: Named struct declarations with
   documentation weren't including that documentation in OpenAPI schemas.

Changes:
- Add allOf wrapper for field docs with schema references (recommended
  OpenAPI 3.0 pattern: OAI/OpenAPI-Specification#2033)
- Include declaration documentation in named schema generation
- Update test data with documented examples
- Regenerate all expected test outputs
@encore-cla
Copy link

encore-cla bot commented Aug 7, 2025

All committers have signed the CLA.

@marcuskohlberg marcuskohlberg requested a review from fredr August 28, 2025 08:52
Copy link
Member

@fredr fredr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Thanks for fixing and sorry for the delay

@fredr fredr merged commit 44f4dec into encoredev:main Sep 2, 2025
4 checks passed
Mugesh2024rj pushed a commit to Mugesh2024rj/encore that referenced this pull request Oct 10, 2025
…coredev#2029)

## 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.Value` is `nil` for schema
references.

**Before:**
```yaml
customer:
  $ref: "#/components/schemas/User"
  # Field documentation was lost
```

**After:**
```yaml
customer:
  description: "Customer who placed the order (not the same as delivery recipient)"
  allOf:
    - $ref: "#/components/schemas/User"
```

### 2. Missing struct-level documentation
Struct declarations with documentation comments weren't including that
documentation in the generated OpenAPI component schemas.

**Before:**
```yaml
"svc.User": {
  "type": "object",
  "properties": {...}
  # Missing title/description from struct docs
}
```

**After:**
```yaml
"svc.DocumentedUser": {
  "type": "object", 
  "title": "DocumentedUser represents a user in the system with profile information",
  "properties": {...}
}
```

## Technical Details

### Field Documentation Fix (lines 75-87)
Uses the `allOf` pattern recommended for OpenAPI 3.0 to add descriptions
to `$ref`. This is the [official
workaround](OAI/OpenAPI-Specification#2033)
for OpenAPI 3.0's limitation where sibling properties to `$ref` are
ignored.

### Struct Documentation Fix (lines 288-302) 
When generating named schema types, include the declaration's
documentation from `g.md.Decls[typ.Id].Doc` in the schema's title and
description fields.

## Testing
- Added documented struct types (`DocumentedUser`, `DocumentedOrder`) to
test data
- Updated all expected test outputs (OpenAPI, TypeScript, JavaScript,
Go)
- Verified both fixes work together in generated specs
- All existing tests pass

## Example Output
The generated OpenAPI now includes comprehensive documentation:

```json
{
  "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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants