feature/openapi docs #2425
Draft
feature/openapi docs #2425
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
Integrates a new `ValidationConstraintsRenderer` to display schema validation constraints in API docs. Updates the relevant views and adds CSS styling for better presentation.
…ursive property rendering support.
Introduces support for displaying response headers in API explorer views. Updates the view logic and adds corresponding CSS styling for consistent and clear presentation.
Introduces logic and styling to display operation-level and document-level servers, as well as security requirements for operations. Updates corresponding views and CSS for consistent appearance.
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
- Remove redundant null checks where boolean flags already guarantee non-null - Add null-forgiving operators where compiler requires them but logic guarantees non-null - Fix null dereference pattern in OperationView request body handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
| var content = operation.RequestBody.Content?.FirstOrDefault().Value; | ||
| var requestContentEntry = operation.RequestBody.Content?.FirstOrDefault(); | ||
| var requestContentType = requestContentEntry?.Key ?? "application/json"; | ||
| var requestMediaType = requestContentEntry?.Value; |
| { | ||
| var refId = baseOption.Ref; | ||
| if (string.IsNullOrEmpty(refId) && baseOption.Schema is OpenApiSchemaReference schemaRef) | ||
| refId = schemaRef.Reference.Id; |
| { | ||
| var refId = primaryOption.Ref; | ||
| if (string.IsNullOrEmpty(refId) && schemaToRender is OpenApiSchemaReference schemaRef) | ||
| refId = schemaRef.Reference?.Id; |
Comment on lines
+58
to
+80
| foreach (var unionSchema in unionSchemas) | ||
| { | ||
| if (unionSchema == null) continue; | ||
| var unionTypeInfo = Model.Analyzer.GetTypeInfo(unionSchema); | ||
| var typeName = unionTypeInfo.TypeName; | ||
| // Strip [] suffix for array types | ||
| var baseName = typeName?.EndsWith("[]") == true ? typeName[..^2] : typeName; | ||
| if (!string.IsNullOrEmpty(baseName) && !SchemaHelpers.IsPrimitiveTypeName(baseName) && Model.AncestorTypes.Contains(baseName)) | ||
| { | ||
| isRecursive = true; | ||
| break; | ||
| } | ||
| // Also check if the union option is an array pointing to an ancestor type | ||
| if (unionTypeInfo.IsArray && unionSchema.Items != null) | ||
| { | ||
| var itemTypeInfo = Model.Analyzer.GetTypeInfo(unionSchema.Items); | ||
| if (!string.IsNullOrEmpty(itemTypeInfo.TypeName) && !SchemaHelpers.IsPrimitiveTypeName(itemTypeInfo.TypeName) && Model.AncestorTypes.Contains(itemTypeInfo.TypeName)) | ||
| { | ||
| isRecursive = true; | ||
| break; | ||
| } | ||
| } | ||
| } |
Comment on lines
+81
to
+89
| foreach (var subSchema in allOf) | ||
| { | ||
| var subProps = GetSchemaProperties(subSchema); | ||
| if (subProps is not null) | ||
| { | ||
| foreach (var prop in subProps) | ||
| _ = props.TryAdd(prop.Key, prop.Value); | ||
| } | ||
| } |
Comment on lines
+64
to
+69
| if (!string.IsNullOrEmpty(refId)) | ||
| { | ||
| // Try to get the resolved schema from the document | ||
| if (document.Components?.Schemas?.TryGetValue(refId, out var resolvedSchema) == true) | ||
| return GetSchemaProperties(resolvedSchema); | ||
| } |
Comment on lines
+363
to
+367
| if (itemInfo is { IsObject: false, HasLink: false }) | ||
| { | ||
| if (string.IsNullOrEmpty(itemInfo.SchemaRef)) | ||
| arrayItemType = itemInfo.TypeName; | ||
| } |
| </p> | ||
| <h1> | ||
| @operation.Summary | ||
| @if (operation.Deprecated == true) |
| { | ||
| <dt id="@path.Name"><a href="#@path.Name"><code>@path.Name</code></a></dt> | ||
| <dd>@Model.RenderMarkdown(path.Description)</dd> | ||
| <div class="path-param @(path.Deprecated == true ? "deprecated" : "")"> |
…ariable' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
| <dt id="[email protected]"> | ||
| <a href="#[email protected]"> | ||
| <code>@path.Name</code> | ||
| @if (path.Deprecated == true) |
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.
API Explorer: Interactive Schema Documentation
This PR introduces a comprehensive API documentation explorer with support for rendering complex OpenAPI schemas, interactive property navigation, and dedicated type pages.
cursorful-video-1767709036040.mp4
Layout & Integration
Updated layout to integrate with assembler builds - constrained widths matching regular documentation pages.
Request & Response Body Rendering
Full support for rendering request and response bodies with:
Nested Property Expansion
Expandable tree structure for complex nested types with property counts and expand/collapse toggles:
Complex Type Support
Union Types (oneOf/anyOf)
Renders union types with grouped variants, showing
XandX[]pairs together:Recursion Detection
Detects recursive type references (including through arrays and unions) and displays a "Recursive" badge to prevent infinite expansion:
Properties like
bool.filter,bool.must,bool.shouldcorrectly show the recursive badge when they reference their parentQueryContainertype.Dedicated Type Pages
Complex types get their own dedicated documentation pages with full property exploration:
Examples
Request and response examples rendered with syntax highlighting:
External Documentation Links
Reference documentation links rendered as buttons below descriptions:
Property-level docs buttons are shown after property descriptions (skipped if type has dedicated page).
Technical Highlights
_PropertyList,_PropertyItem,_UnionOptions,_SchemaTypefor consistent renderinghidden="until-found"for collapsed sections in supported browsers