Devin/1777647229 docs improvements#15
Merged
Merged
Conversation
- Add astro-mermaid integration for Mermaid diagram rendering - Fix RequireAuthorization() examples to use explicit roles/policies - Add HEAD method to supported HTTP methods documentation - Add CsvResponse.From full parameter reference - Add NuGet LinkCard components to Installation page - Rewrite Quick Start with Steps component and auto-registration notes - Add IEndpoint interface detailed explanation to Defining Endpoints - Create Core Primitives page with Mermaid flowchart and class diagram - Improve Endpoint Groups page with concept explanation and API reference - Improve Filters page with concept explanation - Create FAQ page with 3 Q&As - Add FAQ card to index page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…olution Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
📝 WalkthroughWalkthroughThis PR enhances the AxisEndpoints documentation site by adding mermaid diagram support, introducing new core-primitives and FAQ pages, expanding existing guide pages with clearer explanations and examples, restructuring getting-started pages with interactive steps, and improving navigation to make documentation more discoverable. ChangesDocumentation Site Enhancements
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Review rate limit: 9/10 reviews remaining, refill in 6 minutes. Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/src/content/docs/guides/filters.mdx (1)
10-13: ⚡ Quick winConsolidate duplicated middleware-vs-filter explanation.
The new section at Line 10 overlaps with the existing “Difference from middleware” section later in the page (Line 74+). Keeping one canonical explanation will reduce drift.
Proposed cleanup
-## Difference from middleware - -`IEndpointFilter` differs from middleware in that it can be scoped to individual endpoints or groups, rather than applying globally to all requests. - For a FluentValidation example using `IEndpointFilter`, see the [Validation](/guides/validation/) guide. For grouping endpoints, see the [Endpoint Groups](/guides/endpoint-groups/) guide.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/content/docs/guides/filters.mdx` around lines 10 - 13, Duplicate explanation found in the "How It Differs from Middleware" section (heading) which overlaps with the later "Difference from middleware" section; remove the earlier block and either link to or merge its unique points into the canonical later section (the "Difference from middleware" heading) so only one authoritative explanation remains, update any internal anchors or references that pointed to the removed heading to the canonical heading, and ensure examples/phrasing from the removed paragraph are preserved if they add value to the canonical section.docs/src/content/docs/guides/core-primitives.mdx (1)
137-151: ⚡ Quick winAvoid duplicating standard-type explanations.
Line 137–151 largely repeats earlier sections on
IResult,ProblemDetails, andIEndpointFilter, which can drift over time. Consider reducing this to short pointers back to the primary sections.Lean alternative
## Notes on ASP.NET Core Standard Types -AxisEndpoints builds directly on ASP.NET Core standard types. The types below are not AxisEndpoints-specific, so standard Minimal API knowledge applies as-is. - -### `IResult` - -This interface is provided by ASP.NET Core Minimal APIs and represents an HTTP response. It is produced by factory methods such as `Results.Json()`, `Results.Problem()`, `Results.Ok()`, and `Results.NotFound()`. In AxisEndpoints, specifying `IResult` as the return type of `HandleAsync` lets you return different response shapes based on the outcome, such as JSON on success and `ProblemDetails` on error. - -### `ProblemDetails` - -`Microsoft.AspNetCore.Mvc.ProblemDetails` provides the standard error response format defined by RFC 9457 (formerly RFC 7807). It includes fields such as `type`, `title`, `status`, `detail`, and `errors`, which bring consistency to API error responses. AxisEndpoints' DataAnnotations validation filter also returns validation errors in this format. - -### `IEndpointFilter` - -This filter interface is provided by ASP.NET Core Minimal APIs and lets you insert logic into the request pipeline. Unlike middleware, it can be scoped to specific endpoints or groups, which gives you finer control over cross-cutting concerns. +AxisEndpoints builds directly on ASP.NET Core standard types. For details, see the sections above: + +- [`IResult`](`#iresult`) +- [`ProblemDetails`](`#problemdetails`) +- [`IEndpointFilter`](`#iendpointfilter`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/content/docs/guides/core-primitives.mdx` around lines 137 - 151, The section repeating explanations for IResult, ProblemDetails, and IEndpointFilter should be collapsed into a short pointer to the canonical descriptions to avoid duplication; remove the repeated paragraphs under "Notes on ASP.NET Core Standard Types" and replace them with a concise paragraph that references the primary sections (e.g., "See the IResult, ProblemDetails, and IEndpointFilter sections above") and retains a single sentence noting that HandleAsync may return IResult and that ProblemDetails is used for validation errors—keep references to the symbols IResult, ProblemDetails, IEndpointFilter, and HandleAsync so readers can find the detailed explanations elsewhere.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/src/content/docs/getting-started/quick-start.mdx`:
- Line 95: The docs hardcode the endpoint URL "http://localhost:5000/users";
update the verification step to avoid a fixed port by using a placeholder or
referencing the app's configured base URL (e.g., "http://localhost:{PORT}/users"
or "the base URL printed when you start the server") and adjust the sentence to
instruct users to substitute their actual port or use the server's shown URL
instead of 5000.
In `@docs/src/content/docs/guides/core-primitives.mdx`:
- Around line 68-75: The table incorrectly lists the `errors` field as part of
base ProblemDetails; update the docs so the `ProblemDetails` field list (and the
related wording around `ProblemDetails` at the other occurrence) no longer
mentions `errors`, and instead add a brief note that `errors` is provided by
`ValidationProblemDetails` (or point readers to `ValidationProblemDetails` for
validation-specific error details); reference the `ProblemDetails` and
`ValidationProblemDetails` symbols and the `errors` field when making the
correction.
---
Nitpick comments:
In `@docs/src/content/docs/guides/core-primitives.mdx`:
- Around line 137-151: The section repeating explanations for IResult,
ProblemDetails, and IEndpointFilter should be collapsed into a short pointer to
the canonical descriptions to avoid duplication; remove the repeated paragraphs
under "Notes on ASP.NET Core Standard Types" and replace them with a concise
paragraph that references the primary sections (e.g., "See the IResult,
ProblemDetails, and IEndpointFilter sections above") and retains a single
sentence noting that HandleAsync may return IResult and that ProblemDetails is
used for validation errors—keep references to the symbols IResult,
ProblemDetails, IEndpointFilter, and HandleAsync so readers can find the
detailed explanations elsewhere.
In `@docs/src/content/docs/guides/filters.mdx`:
- Around line 10-13: Duplicate explanation found in the "How It Differs from
Middleware" section (heading) which overlaps with the later "Difference from
middleware" section; remove the earlier block and either link to or merge its
unique points into the canonical later section (the "Difference from middleware"
heading) so only one authoritative explanation remains, update any internal
anchors or references that pointed to the removed heading to the canonical
heading, and ensure examples/phrasing from the removed paragraph are preserved
if they add value to the canonical section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1786ded4-86c0-4f4f-948f-11098b795cd5
⛔ Files ignored due to path filters (2)
docs/package-lock.jsonis excluded by!**/package-lock.jsondocs/pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (11)
docs/astro.config.mjsdocs/package.jsondocs/src/content/docs/extensions/csv-helper/csv-export.mdxdocs/src/content/docs/faq.mdxdocs/src/content/docs/getting-started/installation.mdxdocs/src/content/docs/getting-started/quick-start.mdxdocs/src/content/docs/guides/core-primitives.mdxdocs/src/content/docs/guides/defining-endpoints.mdxdocs/src/content/docs/guides/endpoint-groups.mdxdocs/src/content/docs/guides/filters.mdxdocs/src/content/docs/index.mdx
| dotnet run | ||
| ``` | ||
|
|
||
| Send a POST request to `http://localhost:5000/users` to verify that the endpoint works. |
There was a problem hiding this comment.
Avoid hardcoding localhost:5000 in verification step.
At Line 95, the fixed port can mislead users because default local ports vary.
Suggested wording
- Send a POST request to `http://localhost:5000/users` to verify that the endpoint works.
+ Send a POST request to `/users` on the URL shown by `dotnet run` (for example, `https://localhost:xxxx/users`) to verify that the endpoint works.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Send a POST request to `http://localhost:5000/users` to verify that the endpoint works. | |
| Send a POST request to `/users` on the URL shown by `dotnet run` (for example, `https://localhost:xxxx/users`) to verify that the endpoint works. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/getting-started/quick-start.mdx` at line 95, The docs
hardcode the endpoint URL "http://localhost:5000/users"; update the verification
step to avoid a fixed port by using a placeholder or referencing the app's
configured base URL (e.g., "http://localhost:{PORT}/users" or "the base URL
printed when you start the server") and adjust the sentence to instruct users to
substitute their actual port or use the server's shown URL instead of 5000.
Comment on lines
+68
to
+75
| | Field | Description | | ||
| | --- | --- | | ||
| | `type` | URI that identifies the error category | | ||
| | `title` | Short summary of the error | | ||
| | `status` | HTTP status code | | ||
| | `detail` | Detailed explanation of the error | | ||
| | `errors` | Additional details such as validation errors | | ||
|
|
There was a problem hiding this comment.
ProblemDetails field list is slightly inaccurate.
Line 74 (and Line 147 wording) presents errors as a common ProblemDetails field. That field is typically associated with ValidationProblemDetails, not base ProblemDetails.
Suggested doc correction
| Field | Description |
| --- | --- |
| `type` | URI that identifies the error category |
| `title` | Short summary of the error |
| `status` | HTTP status code |
| `detail` | Detailed explanation of the error |
-| `errors` | Additional details such as validation errors |
+| `instance` | URI reference to the specific occurrence of the problem |-`Microsoft.AspNetCore.Mvc.ProblemDetails` provides the standard error response format defined by RFC 9457 (formerly RFC 7807). It includes fields such as `type`, `title`, `status`, `detail`, and `errors`, which bring consistency to API error responses. AxisEndpoints' DataAnnotations validation filter also returns validation errors in this format.
+`Microsoft.AspNetCore.Mvc.ProblemDetails` provides the standard error response format defined by RFC 9457 (formerly RFC 7807). It includes fields such as `type`, `title`, `status`, `detail`, and `instance`, which bring consistency to API error responses. AxisEndpoints' DataAnnotations validation filter typically returns `ValidationProblemDetails`, which adds an `errors` member for validation failures.Also applies to: 147-147
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/guides/core-primitives.mdx` around lines 68 - 75, The
table incorrectly lists the `errors` field as part of base ProblemDetails;
update the docs so the `ProblemDetails` field list (and the related wording
around `ProblemDetails` at the other occurrence) no longer mentions `errors`,
and instead add a brief note that `errors` is provided by
`ValidationProblemDetails` (or point readers to `ValidationProblemDetails` for
validation-specific error details); reference the `ProblemDetails` and
`ValidationProblemDetails` symbols and the `errors` field when making the
correction.
This was referenced May 2, 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
1 participant
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 by CodeRabbit