diff --git a/.github/workflows/actions-lint.yml b/.github/workflows/lint.yml
similarity index 72%
rename from .github/workflows/actions-lint.yml
rename to .github/workflows/lint.yml
index 5e583ef1e6..9a7dd0b133 100644
--- a/.github/workflows/actions-lint.yml
+++ b/.github/workflows/lint.yml
@@ -1,51 +1,58 @@
-name: actions-lint
-
-on:
- push:
- branches: [ master ]
- paths-ignore:
- - '**/*.gitattributes'
- - '**/*.gitignore'
- - '**/*.md'
- pull_request:
- branches: [ master ]
- workflow_dispatch:
-
-permissions: {}
-
-env:
- FORCE_COLOR: 3
- TERM: xterm
- ZIZMOR_VERSION: '1.14.1'
-
-jobs:
- lint:
- runs-on: ubuntu-latest
-
- permissions:
- actions: read
- contents: read
- security-events: write
-
- steps:
-
- - name: Checkout code
+name: lint
+
+on:
+ push:
+ branches: [ master ]
+ paths-ignore:
+ - '**/*.gitattributes'
+ - '**/*.gitignore'
+ - '**/*.md'
+ pull_request:
+ branches: [ master ]
+ workflow_dispatch:
+
+permissions: {}
+
+env:
+ FORCE_COLOR: 3
+ TERM: xterm
+ ZIZMOR_VERSION: '1.16.3'
+
+jobs:
+ lint:
+ runs-on: ubuntu-latest
+
+ permissions:
+ actions: read
+ contents: read
+ security-events: write
+
+ steps:
+
+ - name: Checkout code
uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
- with:
- filter: 'tree:0'
- persist-credentials: false
- show-progress: false
-
- - name: Add actionlint problem matcher
- run: echo "::add-matcher::.github/actionlint-matcher.json"
-
- - name: Lint workflows
- uses: docker://rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
- with:
- args: -color
-
- - name: Lint workflows with zizmor
- uses: zizmorcore/zizmor-action@e673c3917a1aef3c65c972347ed84ccd013ecda4 # v0.2.0
- with:
- persona: pedantic
- version: ${{ env.ZIZMOR_VERSION }}
+ with:
+ filter: 'tree:0'
+ persist-credentials: false
+ show-progress: false
+
+ - name: Add actionlint problem matcher
+ run: echo "::add-matcher::.github/actionlint-matcher.json"
+
+ - name: Lint workflows
+ uses: docker://rhysd/actionlint:1.7.9@sha256:a0383f60d92601e2694e24b24d37df7b6a40bed7cedbc447611c50009bf02d94
+ with:
+ args: -color
+
+ - name: Lint workflows with zizmor
+ uses: zizmorcore/zizmor-action@e673c3917a1aef3c65c972347ed84ccd013ecda4 # v0.2.0
+ with:
+ persona: pedantic
+ version: ${{ env.ZIZMOR_VERSION }}
+
+ - name: Lint markdown
+ uses: DavidAnson/markdownlint-cli2-action@30a0e04f1870d58f8d717450cc6134995f993c63 # v21.0.0
+ with:
+ config: '.markdownlint.json'
+ globs: |
+ **/*.md
diff --git a/.github/zizmor.yml b/.github/zizmor.yml
index ad6d776482..ab690df920 100644
--- a/.github/zizmor.yml
+++ b/.github/zizmor.yml
@@ -1,5 +1,9 @@
rules:
anonymous-definition:
disable: true
+ concurrency-limits:
+ disable: true
+ dependabot-cooldown:
+ disable: true
undocumented-permissions:
disable: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c1211fe76c..ec426ae8bf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,22 +1,21 @@
-Contributing to Swashbuckle.AspNetCore
-=========
+# Contributing to Swashbuckle.AspNetCore
Contributions to Swashbuckle.AspNetCore are welcomed in the form of constructive, reproducible bug reports, feature requests that align to the project's goals, or better still a PR that's accompanied with passing tests.
If you have general questions or feedback about using Swashbuckle.AspNetCore, PLEASE DON'T CREATE AN ISSUE AND POST TO STACKOVERFLOW INSTEAD.
-## Bug Reports ##
+## Bug Reports
If you're reporting a bug, please include a clear description of the issue, the version of Swashbuckle.AspNetCore you're using, and a set of clear repro steps.
Please remember that Swashbuckle.AspNetCore is a free and open-source project provided to the community with zero financial gain to the author(s). Any issues deemed to have a negative or arrogant tone will be closed without response.
-## Feature Requests ##
+## Feature Requests
-Fundamentally, Swashbuckle.AspNetCore is a library that attempts to generate an accurate description for APIs built on ASP.NET Core, using [Swagger 2.0](https://swagger.io/docs/specification/2-0/basic-structure/), according to the routes, controllers and models that have been implemented. So, the resulting API documentation is driven by "actual" behavior as opposed to "intended" behavior. This is an important distinction to consider when submitting feature requests. For example, a feature that leverages built-in attributes that affect runtime behavior (e.g. AuthorizeAttribute, RequiredAttribute etc.) would be more aligned to the project goals than one that introduces custom attributes that drive documentation and nothing else.
+Fundamentally, Swashbuckle.AspNetCore is a library that attempts to generate an accurate description for APIs built on ASP.NET Core, using [OpenAPI 3.0](https://swagger.io/docs/specification/v3_0/basic-structure/) (or [Swagger 2.0](https://swagger.io/docs/specification/2-0/basic-structure/)), according to the routes, controllers and models that have been implemented. So, the resulting API documentation is driven by "actual" behavior as opposed to "intended" behavior. This is an important distinction to consider when submitting feature requests. For example, a feature that leverages built-in attributes that affect runtime behavior (e.g. AuthorizeAttribute, RequiredAttribute etc.) would be more aligned to the project goals than one that introduces custom attributes that drive documentation and nothing else.
It's also worth noting that Swashbuckle.AspNetCore leverages the [swagger-ui project](https://github.com/swagger-api/swagger-ui) but doesn't actually implement any UI code. If you have a bug report or feature request that's UI-specific, PLEASE DON'T CREATE AN ISSUE HERE AND POST TO THE SWAGGER-UI REPO INSTEAD.
-## Pull Requests ##
+## Pull Requests
If you've identified a feature/bug fix that aligns to the project goals, or even just an addition to the docs, please submit a Pull Request (PR). If applicable, include tests and ensure all tests are passing locally before you commit.
diff --git a/README.md b/README.md
index 1ab4167ee1..f0df85fee4 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,8 @@ for more details.
[redoc-version-v7-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdomaindrivendev%2FSwashbuckle.AspNetCore%2Frefs%2Ftags%2Fv7.3.2%2Fsrc%2FSwashbuckle.AspNetCore.ReDoc%2Fpackage.json&query=%24.dependencies.redoc&style=flat&label=Redoc
[redoc-version-v7-release]: https://github.com/Redocly/redoc/releases/tag/v2.4.0
+## Getting Started
+
First install the kitchen-sink NuGet package into your ASP.NET Core application:
```terminal
@@ -295,7 +297,7 @@ Additionally, there are add-on packages (CLI tools, [an alternate UI using Redoc
### "Core" Packages
| **Package** | **NuGet** | **Description** |
-|-------------|--------------------|-----------------|
+| ----------- | --------- | --------------- |
| [Swashbuckle.AspNetCore.Swagger][swashbuckle-aspnetcore-swagger] | [][swashbuckle-aspnetcore-swagger] | Exposes OpenAPI JSON endpoints. It expects an implementation of `ISwaggerProvider` to be registered in the DI container, which it queries to retrieve `OpenApiDocument` instance(s) that are then exposed as serialized JSON. |
| [Swashbuckle.AspNetCore.SwaggerGen][swashbuckle-aspnetcore-swaggergen] | [][swashbuckle-aspnetcore-swaggergen] | Injects an implementation of `ISwaggerProvider` that can be used by the above component. This particular implementation generates `OpenApiDocument` instance(s) from your application endpoints (controllers, minimal endpoints etc.). |
| [Swashbuckle.AspNetCore.SwaggerUI][swashbuckle-aspnetcore-swaggerui] | [][swashbuckle-aspnetcore-swaggerui] | Exposes an embedded version of [swagger-ui][swagger-ui]. You specify the API endpoints where it can obtain OpenAPI documents from, and it uses them to power interactive documentation for your API. |
@@ -303,7 +305,7 @@ Additionally, there are add-on packages (CLI tools, [an alternate UI using Redoc
### Additional Packages
| **Package** | **NuGet** | **Description** |
-|-------------|--------------------|-----------------|
+| ----------- | --------- | --------------- |
| [Swashbuckle.AspNetCore.Annotations][swashbuckle-aspnetcore-annotations] | [][swashbuckle-aspnetcore-annotations] | Includes a set of custom attributes that can be applied to controllers/endpoints, actions and models to enrich the generated documentation. |
| [Swashbuckle.AspNetCore.Cli][swashbuckle-aspnetcore-cli] | [][swashbuckle-aspnetcore-cli] | Provides a command line interface (CLI) for retrieving OpenAPI documents directly from an application start-up assembly and then writing to a file. |
| [Swashbuckle.AspNetCore.ReDoc][swashbuckle-aspnetcore-redoc] | [][swashbuckle-aspnetcore-redoc] | Exposes an embedded version of the [Redoc UI][redoc] (an alternative to [swagger-ui][swagger-ui]). |
@@ -313,7 +315,7 @@ Additionally, there are add-on packages (CLI tools, [an alternate UI using Redoc
These packages are provided by the .NET open-source community.
| **Package** | **NuGet** | **Description** |
-|-------------|--------------------|-----------------|
+| ----------- | --------- | --------------- |
| [Swashbuckle.AspNetCore.Filters][swashbuckle-aspnetcore-filters] | [][swashbuckle-aspnetcore-filters] | Some useful Swashbuckle.AspNetCore filters which add additional documentation, e.g. request and response examples, authorization information, etc. See its README for more details. |
| [Unchase.Swashbuckle.AspNetCore.Extensions][unchase-swashbuckle-aspnetcore-extensions] | [][unchase-swashbuckle-aspnetcore-extensions] | Some useful extensions (filters), which add additional documentation, e.g. hide `PathItems` for unaccepted roles, fix enumerations for client code generation, etc. See its README for more details. |
| [MicroElements.Swashbuckle.FluentValidation][microelements-swashbuckle-fluentvalidation] | [][microelements-swashbuckle-fluentvalidation] | Use [FluentValidation][fluentvalidation] rules instead of ComponentModel attributes to augment generated OpenAPI schemas. |
@@ -325,8 +327,8 @@ The steps described above will get you up and running with minimal set up. Howev
Check out the table below for the full list of possible configuration options.
-| **Component** | **Configuration and Customization** |
-| ------------- | ----------------------------------- |
+| **Component** | **Configuration and Customization** |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Swashbuckle.AspNetCore.Swagger** | [Change the Path for OpenAPI JSON Endpoints](docs/configure-and-customize-swagger.md#change-the-path-for-openapi-json-endpoints) |
| | [Modify OpenAPI with Request Context](docs/configure-and-customize-swagger.md#modify-openapi-with-request-context) |
| | [Serialize OpenAPI JSON in the 3.1 format](docs/configure-and-customize-swagger.md#serialize-openapi-in-the-31-format) |
diff --git a/Swashbuckle.AspNetCore.slnx b/Swashbuckle.AspNetCore.slnx
index 63e77ce466..78c16b450f 100644
--- a/Swashbuckle.AspNetCore.slnx
+++ b/Swashbuckle.AspNetCore.slnx
@@ -27,10 +27,10 @@
-
+
diff --git a/docs/migrating-to-v10.md b/docs/migrating-to-v10.md
index c7ad61af54..354e55b2b2 100644
--- a/docs/migrating-to-v10.md
+++ b/docs/migrating-to-v10.md
@@ -85,6 +85,7 @@ Migrating to Swashbuckle.AspNetCore v10+ will likely involve changes in the foll
}
}
```
+
- Update any use of `.Reference` properties (e.g. `OpenApiSchema.ReferenceV3`) to use the new `*Reference` class instead (e.g. `OpenApiSchemaReference`).
- Replace usage of the `OpenApiSchema.Type` property using a string (e.g. `"string"` or `"boolean"`) with the `JsonSchemaType` flags enumeration.
- Replace usage of the `OpenApiSchema.Nullable` property by OR-ing the `JsonSchemaType.Null` value to `OpenApiSchema.Type` (e.g. `schema.Type |= JsonSchemaType.Null;`).