Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 23 additions & 6 deletions .opencode/skills/docs-site/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,33 @@ signature accuracy of code examples, also apply the `docs-accuracy` skill.
7. **Keep docs aligned with `src/`.** Page content (type names, signatures, package ids,
install commands, code examples) must match the actual source. For detailed
accuracy checks, also apply the `docs-accuracy` skill.
8. **READMEs feed the site.** Package READMEs (`src/*/README.md`) are the source of
truth for package-level content. When building or updating the site, mirror
their accurate content into `docs/` pages, but only after verifying the README
is up to date with the source (apply `docs-accuracy`). Do not copy stale
README content into the site.
8. **Badges.** Package pages carry the same badge block as their package README
(NuGet, Downloads, License, .NET) with `style=for-the-badge`. This includes the
root `docs/index.md` (the `CoreSystem.OpenApi` package page) and each package
index such as `docs/Swashbuckle/index.md`.
9. **Emoji headings.** Docs pages use the same emoji vocabulary as the package
READMEs (see the `readme` skill), so the site matches the registry listing:
- ⚑ package / title
- ✨ features
- πŸ“¦ installation
- πŸš€ quick start
- 🧩 components
- βš™οΈ configuration
- πŸ— architecture
- πŸ“– documentation
- 🀝 contributing
- πŸ“„ license
- βœ… feature bullets
10. **READMEs feed the site.** Package READMEs (`src/*/README.md`) are the source of
truth for package-level content. When building or updating the site, mirror
their accurate content into `docs/` pages, but only after verifying the README
is up to date with the source (apply `docs-accuracy`). Do not copy stale
README content into the site.

## Verification

```
mkdocs build --strict
```

Must exit 0 with no warnings.
Must exit 0 with no warnings.
12 changes: 7 additions & 5 deletions CoreSystem.OpenApi.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,22 @@
<File Path=".github/workflows/samples-smoke.yml" />
</Folder>
<Folder Name="/docs/">
<File Path="docs/Attributes.md" />
<File Path="docs/GettingStarted.md" />
<File Path="docs/index.md" />
</Folder>
<Folder Name="/docs/OpenApi/">
<File Path="docs/OpenApi/Configuration.md" />
<File Path="docs/OpenApi/GettingStarted.md" />
<File Path="docs/OpenApi/index.md" />
<File Path="docs/OpenApi/ProblemResponses.md" />
<Folder Name="/docs/Swashbuckle/">
<File Path="docs/Swashbuckle/Configuration.md" />
<File Path="docs/Swashbuckle/GettingStarted.md" />
<File Path="docs/Swashbuckle/index.md" />
<File Path="docs/Swashbuckle/ProblemResponses.md" />
</Folder>
<Folder Name="/Elementos de la soluciΓ³n/">
<File Path="CORE-SYSTEM-STANDARDS.md" />
<File Path="Directory.Build.props" />
<File Path="Directory.Packages.props" />
<File Path="mkdocs.yml" />
<File Path="README.md" />
</Folder>
<Folder Name="/samples/">
<Project Path="samples/Core.OpenApi.Swashbuckle.Baseline.Sample/Core.OpenApi.Swashbuckle.Baseline.Sample.csproj" />
Expand Down
10 changes: 5 additions & 5 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
<PackageVersion Include="Swashbuckle.AspNetCore.Annotations" Version="9.0.6" />
<PackageVersion Include="Swashbuckle.AspNetCore.Filters" Version="9.0.1" />
<PackageVersion Include="Microsoft.OpenApi" Version="1.6.25" />
<PackageVersion Include="coverlet.collector" Version="10.1.0" />
<PackageVersion Include="coverlet.msbuild" Version="10.1.0" />
<PackageVersion Include="coverlet.collector" Version="10.1.1" />
<PackageVersion Include="coverlet.msbuild" Version="10.1.1" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.12.0" />
<PackageVersion Include="xunit.runner.visualstudio" Version="4.0.1" />
<PackageVersion Include="xunit.v3" Version="4.0.2" />
<PackageVersion Include="xunit.v3" Version="4.0.3" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
<PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="8.0.32" />
Expand All @@ -29,8 +29,8 @@
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="9.0.21" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
<PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="10.0.13" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.13" />
<PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="10.0.15" />
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.15" />
</ItemGroup>
<ItemGroup>
</ItemGroup>
Expand Down
17 changes: 17 additions & 0 deletions docs/Attributes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# 🧩 Attributes

Response attributes declare the responses of an endpoint in the generated document.

- `ProducesOkAttribute<T>` - declares a `200 OK` with a typed body.
- `ProducesCreatedAttribute<T>` - declares a `201 Created` with a typed body.
- `ProducesNoContentAttribute` - declares a `204 No Content`.
- `ProducesNotFoundProblemAttribute` - declares a `404` problem response.
- `ProducesValidationProblemAttribute` - declares a `400` validation problem response.
- `ProducesTooManyRequestsProblemAttribute` - declares a `429` problem response.
- `ProducesConflictProblemAttribute` - declares a `409` problem response.

## Next Steps

Choose a package to continue learning.

- [CoreSystem.OpenApi.Swashbuckle](Swashbuckle/index.md) to generate the document
22 changes: 19 additions & 3 deletions docs/GettingStarted.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,20 @@
# Getting Started
# πŸš€ Getting Started

Install the package:
## Prerequisites

Before getting started, ensure you have:

- .NET 8 SDK, .NET 9 SDK or .NET 10 SDK
- An IDE such as Visual Studio 2022 or JetBrains Rider

## πŸ“¦ Installation

```bash
dotnet add package CoreSystem.OpenApi
```

## First Example

Reference the package and annotate controllers with the response attributes:

```csharp
Expand All @@ -17,4 +26,11 @@ public async Task<IActionResult> Create(CreateOrderRequest request)
```

The attributes declare the response types (`200`, `201`, `204`, `400`, `404`, `429`)
in the generated document. They can be used on their own, without any OpenAPI provider.
in the generated document. They can be used on their own, without any OpenAPI provider.

## Next Steps

Choose a topic to continue learning.

- [Attributes](Attributes.md)
- [CoreSystem.OpenApi.Swashbuckle](Swashbuckle/index.md) to generate the document
29 changes: 0 additions & 29 deletions docs/OpenApi/ProblemResponses.md

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Configuration
# βš™οΈ Configuration

Configure via `CoreOpenApiOptions` (extends `OpenApiOptions`):

Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,27 @@
# Getting Started
# πŸš€ Getting Started

Welcome to **CoreSystem.OpenApi.Swashbuckle**, the Swashbuckle integration for
CoreSystem-based APIs.

## Prerequisites

Before getting started, ensure you have:

- .NET 8 SDK, .NET 9 SDK or .NET 10 SDK
- An IDE such as Visual Studio 2022 or JetBrains Rider
- Basic knowledge of C# and Dependency Injection

## Installation

Install the package:

```bash
dotnet add package CoreSystem.OpenApi.Swashbuckle
```

Register the document and map the endpoint:
## Register the services

Register the document and map the endpoint during application startup:

```csharp
using Core.OpenApi.Swashbuckle.DependencyInjection;
Expand All @@ -28,8 +43,7 @@ var app = builder.Build();
app.UseCoreOpenApi();
```

The application now serves `/swagger/v1/swagger.json`, `/swagger` (Swagger UI) and
`swagger-original/v1/swagger.json` (unpatched output).
## First Example

Annotate controllers with the response attributes:

Expand All @@ -39,4 +53,14 @@ using Core.OpenApi.Attributes;
[HttpPost]
[ProducesCreated<Item>]
public ActionResult<Item> Create([FromBody] Item item) => ...
```
```

The application now serves `/swagger/v1/swagger.json`, `/swagger` (Swagger UI) and
`swagger-original/v1/swagger.json` (unpatched output).

## Next Steps

Choose a topic to continue learning.

- [Configuration](Configuration.md)
- [Problem Responses](ProblemResponses.md)
58 changes: 58 additions & 0 deletions docs/Swashbuckle/ProblemResponses.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# 🧩 Problem Responses

Every configured error response is declared once in `components.responses` and
referenced from operations that already document the status code.

```csharp
builder.Services.AddCoreOpenApi(options =>
{
options.ProblemResponses.SchemaId = "CoreProblemDetails";
options.ProblemResponses.ValidationSchemaId = "CoreValidationProblemDetails";
options.ProblemResponses.TypePrefix = "urn:orders:error:";
options.ProblemResponses.TraceIdExample =
"00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01";

// Rate limiting applies to every endpoint -> document 429 everywhere.
options.ProblemResponses.Definitions
.Single(d => d.StatusCode == "429")
.IncludeWhenMissing = true;
});
```

`SchemaId` names the component that every problem response references. Its default
is `CoreProblemDetails`, the problem type shipped by this library. The example above
sets the default explicitly for clarity.

> **Note:** `SchemaId` can name any schema present in the document, either one from this
> library or the error class of an external provider. The problem response attributes
> (`ProducesNotFoundProblemAttribute`, `ProducesTooManyRequestsProblemAttribute`, and the
> others) keep documenting `CoreProblemDetails` on their own, so changing `SchemaId` does not
> affect them. The only failure is a `SchemaId` whose name does not exist in
> `components.schemas`, which leaves a dangling `$ref`.

To use your own error type, set `SchemaType` (and `ValidationSchemaType` for the `400`) to
the class that defines it. The library registers that schema in the document, so the
responses resolve. The class name must equal `SchemaId`, or the configuration fails:

```csharp
builder.Services.AddCoreOpenApi(options =>
{
options.ProblemResponses.SchemaId = nameof(AppProblemDetails);
options.ProblemResponses.SchemaType = typeof(AppProblemDetails);
});
```

The shared schemas `CoreProblemDetails` and `CoreValidationProblemDetails` are always
registered in `components.schemas` while `ProblemResponses.Enabled` is `true`, even when no
operation uses them directly. This prevents the `Could not resolve reference` error for
responses such as `429` that are added to every operation.

`ValidationSchemaId` names the schema of the validation (`400`) response, `ValidationError`.
When it is not set, the `400` response uses `CoreValidationProblemDetails` (the body documented by
`ProducesValidationProblemAttribute`) while `SchemaId` keeps its default. If you change
`SchemaId`, the `400` response follows it. Set `ValidationSchemaId` explicitly when your API
returns a different validation type, and make sure that schema exists in the document.

`IncludeWhenMissing` defaults to `false`, so a status code is only added to
operations that already declare it. An existing `400` is replaced only when it
already looks like a problem response.
12 changes: 7 additions & 5 deletions docs/OpenApi/index.md β†’ docs/Swashbuckle/index.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# OpenAPI
# ⚑ CoreSystem.OpenApi.Swashbuckle

`CoreSystem.OpenApi.Swashbuckle` provides the OpenAPI/Swagger infrastructure shared
by CoreSystem-based APIs on .NET 8, .NET 9 and .NET 10.

![NuGet](https://img.shields.io/nuget/v/CoreSystem.OpenApi.Swashbuckle?style=for-the-badge)
![Downloads](https://img.shields.io/nuget/dt/CoreSystem.OpenApi.Swashbuckle?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%209.0%20%7C%2010.0-blue?style=for-the-badge)

- One-call wiring: `AddCoreOpenApi` / `UseCoreOpenApi`
- Bearer security scheme applied to every operation
- Response attributes (from the base `CoreSystem.OpenApi` package): `ProducesOkAttribute<T>`, `ProducesCreatedAttribute<T>`, `ProducesNoContentAttribute`
- Shared problem-details responses declared once as `$ref` components
- Patched document cached in memory

See [Getting Started](GettingStarted.md), [Configuration](Configuration.md) and
[Problem Responses](ProblemResponses.md).
- Patched document cached in memory
32 changes: 15 additions & 17 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,21 @@
# CoreSystem.OpenApi
# ⚑ CoreSystem.OpenApi

Production-ready OpenAPI base contracts and models for .NET 8, .NET 9 and .NET 10.
Base contracts and models for .NET 8, .NET 9 and .NET 10.

CoreSystem.OpenApi contains the base contracts, options and models shared by every
OpenAPI provider implementation. It depends on ASP.NET Core but carries no
provider-specific code, so it can be referenced on its own for the response
attributes.
CoreSystem.OpenApi contains the base contracts, options and models shared by every OpenAPI provider implementation. It depends on ASP.NET Core but carries no provider-specific code, so it can be referenced on its own for the response attributes.

## Response attributes
![NuGet](https://img.shields.io/nuget/v/CoreSystem.OpenApi?style=for-the-badge)
![Downloads](https://img.shields.io/nuget/dt/CoreSystem.OpenApi?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%209.0%20%7C%2010.0-blue?style=for-the-badge)

- `ProducesOkAttribute<T>` β€” declares a `200 OK` with a typed body.
- `ProducesCreatedAttribute<T>` β€” declares a `201 Created` with a typed body.
- `ProducesNoContentAttribute` β€” declares a `204 No Content`.
- `ProducesNotFoundProblemAttribute` β€” declares a `404` problem response.
- `ProducesValidationProblemAttribute` β€” declares a `400` validation problem response.
- `ProducesTooManyRequestsProblemAttribute` β€” declares a `429` problem response.
## ✨ Features

## Installation
- βœ… Shared options, descriptors and problem-details contracts
- βœ… Response attributes usable without any provider
- βœ… Problem response definitions with configurable replacement modes
- βœ… Bearer security scheme options

```bash
dotnet add package CoreSystem.OpenApi
```
See [Getting Started](GettingStarted.md) and [Attributes](Attributes.md).

For document generation, see [CoreSystem.OpenApi.Swashbuckle](Swashbuckle/index.md).
15 changes: 6 additions & 9 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,6 @@ plugins:
- search
- mermaid2

extra_javascript:
- javascripts/external-documentation-links.js

markdown_extensions:
- admonition
- tables
Expand All @@ -37,12 +34,12 @@ markdown_extensions:

nav:
- Home: index.md

- Getting Started: GettingStarted.md
- Attributes: Attributes.md

- Packages:
- OpenAPI:
- Overview: OpenApi/index.md
- Getting Started: OpenApi/GettingStarted.md
- Configuration: OpenApi/Configuration.md
- Problem Responses: OpenApi/ProblemResponses.md
- Swashbuckle:
- Overview: Swashbuckle/index.md
- Getting Started: Swashbuckle/GettingStarted.md
- Configuration: Swashbuckle/Configuration.md
- Problem Responses: Swashbuckle/ProblemResponses.md
Loading
Loading