Add markdown linter (#3673)

- Add markdownlint.
- Fix markdownlint warnings.
- Update actionlint to the latest version.
- Update zizmor to the latest version.

Author: martincostello

.github/workflows/actions-lint.yml .github/workflows/lint.yml.github/workflows/actions-lint.yml renamed to .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

.github/zizmor.yml

@@ -1,5 +1,9 @@
 rules:
   anonymous-definition:
     disable: true
+  concurrency-limits:
+    disable: true
+  dependabot-cooldown:
+    disable: true
   undocumented-permissions:
     disable: true

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.

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,15 +297,15 @@ Additionally, there are add-on packages (CLI tools, [an alternate UI using Redoc
 ### "Core" Packages
 
 | **Package** | **NuGet** | **Description** |
-|-------------|--------------------|-----------------|
+| ----------- | --------- | --------------- |
 | [Swashbuckle.AspNetCore.Swagger][swashbuckle-aspnetcore-swagger] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.Swagger?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.SwaggerGen?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.SwaggerUI?logo=nuget&label=Latest&color=blue)][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. |
 
 ### Additional Packages
 
 | **Package** | **NuGet** | **Description** |
-|-------------|--------------------|-----------------|
+| ----------- | --------- | --------------- |
 | [Swashbuckle.AspNetCore.Annotations][swashbuckle-aspnetcore-annotations] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.Annotations?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.Cli?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.ReDoc?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.Filters?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/Unchase.Swashbuckle.AspNetCore.Extensions?logo=nuget&label=Latest&color=blue)][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] | [![NuGet](https://img.shields.io/nuget/v/MicroElements.Swashbuckle.FluentValidation?logo=nuget&label=Latest&color=blue)][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)                                                      |

Swashbuckle.AspNetCore.slnx

@@ -27,10 +27,10 @@
     <File Path=".github/update-baselines.ps1" />
   </Folder>
   <Folder Name="/Solution Items/.github/workflows/">
-    <File Path=".github/workflows/actions-lint.yml" />
     <File Path=".github/workflows/build.yml" />
     <File Path=".github/workflows/bump-version.yml" />
     <File Path=".github/workflows/codeql-analysis.yml" />
+    <File Path=".github/workflows/lint.yml" />
     <File Path=".github/workflows/ossf-scorecard.yml" />
     <File Path=".github/workflows/release.yml" />
     <File Path=".github/workflows/stale.yml" />

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;`).