diff --git a/docs/features/logging.md b/docs/features/logging.md index 783dd9f3..f31bd227 100644 --- a/docs/features/logging.md +++ b/docs/features/logging.md @@ -3,14 +3,20 @@ title: "Logging unhandled exceptions via ASP.NET Core middleware" layout: default --- -## Logging unhandled exceptions - -### Introduction +# Logging unhandled exceptions The `ExceptionHandlingMiddleware` class can be added to the ASP.NET Core pipeline to log unhandled exceptions that are thrown during request processing. The unhandled exceptions are caught by this middleware component and are logged through the `ILogger` implementations that are configured inside the project. -### Usage +## Installation + +This feature requires to install our NuGet package + +```shell +PM > Install-Package Arcus.WebApi.Logging +``` + +## Usage To use this middleware, add the following line of code in the `Startup.Configure` method: diff --git a/docs/features/openapi-securitydefinitions.md b/docs/features/openapi/security-definitions.md similarity index 84% rename from docs/features/openapi-securitydefinitions.md rename to docs/features/openapi/security-definitions.md index bf5ae371..45180846 100644 --- a/docs/features/openapi-securitydefinitions.md +++ b/docs/features/openapi/security-definitions.md @@ -3,14 +3,20 @@ title: "Adding security information to OpenAPI documentation" layout: default --- -## Adding OAuth security definition to API operations - -### Introduction +# Adding OAuth security definition to API operations When an API is secured via OAuth, it is helpful if the Open API documentation makes this clear via a security scheme and the API operations that require authorization automatically inform the consumer that it is possible that a 401 Unauthorized or 403 Forbidden response is returned. The `OAuthAuthorizeOperationFilter` that is part of this package exposes this functionality. -### Usage +## Installation + +This feature requires to install our NuGet package + +```shell +PM > Install-Package Arcus.WebApi.OpenApi.Extensions +``` + +## Usage To indicate that an API is protected by OAuth, you need to add `AuthorizeCheckOperationFilter` as an `OperationFilter` when configuring Swashbuckles Swagger generation: diff --git a/docs/features/auth/certificate.md b/docs/features/security/auth/certificate.md similarity index 96% rename from docs/features/auth/certificate.md rename to docs/features/security/auth/certificate.md index 72c4c89b..8e9c5988 100644 --- a/docs/features/auth/certificate.md +++ b/docs/features/security/auth/certificate.md @@ -3,6 +3,8 @@ title: "Authentication with certificate via ASP.NET Core authentication filters" layout: default --- +# Authentication with certificate + The `Arcus.WebApi.Security` package provides a mechanism that uses the client certificate of the request to grant access to a web application. This authentication process consists of following parts: @@ -15,6 +17,14 @@ The package allows two ways to configure this type of authentication mechanism i - [Globally enforce certificate authentication](#Globally-enforce-certificate-authentication) - [Enforce certificate authentication per controller or operation](#Enforce-certificate-authentication-per-controller-or-operation) +## Installation + +This feature requires to install our NuGet package + +```shell +PM > Install-Package Arcus.WebApi.Security.Authentication +``` + ## Globally enforce certificate authentication ### Introduction diff --git a/docs/features/auth/shared-access-key.md b/docs/features/security/auth/shared-access-key.md similarity index 94% rename from docs/features/auth/shared-access-key.md rename to docs/features/security/auth/shared-access-key.md index 0950c972..72bd9139 100644 --- a/docs/features/auth/shared-access-key.md +++ b/docs/features/security/auth/shared-access-key.md @@ -3,6 +3,8 @@ title: "Authentication with shared access keys via ASP.NET Core authentication f layout: default --- +# Authentication with shared access keys + The `Arcus.WebApi.Security` package provides a mechanism that uses shared access keys to grant access to a web application. This authentication process consists of two parts: @@ -12,6 +14,14 @@ This authentication process consists of two parts: The package allows two ways to configure this type of authentication mechanmism in an ASP.NET application: - [Global Shared access key authentication](#globally-enforce-shared-access-key-authentication) - [Shared access key authentication per controller or operation](#enforce-shared-access-key-authentication-per-controller-or-operation) + +## Installation + +This feature requires to install our NuGet package + +```shell +PM > Install-Package Arcus.WebApi.Security.Authentication +``` ## Globally enforce shared access key authentication diff --git a/docs/index.md b/docs/index.md index 537eceb0..8c1e98b9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,38 +18,18 @@ To install all Arcus.WebApi packages: PM > Install-Package Arcus.WebApi.All ``` -To install the Arcus.WebApi.Logging package: - -```shell -PM > Install-Package Arcus.WebApi.Logging -``` - -To install the Arcus.WebApi.OpenApi.Extensions package: - -```shell -PM > Install-Package Arcus.WebApi.OpenApi.Extensions -``` +For more granular packages we recommend reading the documentation. # Features -## Arcus.WebApi.Security - -The `Arcus.WebApi.Security` package contains functionality to easily add security capabilities to an API. - -- [Shared access key authentication](features/auth/shared-access-key.md) -- [Certificate authentication](features/auth/certificate.md) - -## Arcus.WebApi.Logging - -The `Arcus.WebApi.Logging` package contains functionality that can be incorporated in API projects to easily add logging capabilities to an API project. - -- [Logging unhandled exceptions](features/logging.md) - -## OpenAPI Extensions - -The `Arcus.WebApi.OpenApi.Extensions` package contains functionality that can be used to easily improve the Open API documentation of an API when making using of Swashbuckle. - -- [Exposing security information in Swashbuckle documentation](features/openapi-securitydefinitions.md) +- **Security** + - Authentication + - [Shared access key authentication](features/security/auth/shared-access-key) + - [Certificate authentication](features/security/auth/certificate) +- **Logging** + - [Logging unhandled exceptions](features/logging) +- **OpenAPI** + - [Exposing security information in Swashbuckle documentation](features/openapi/security-definitions) # License This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.