Digipolis Swagger library

Digipolis Antwerp uses the Swagger library for API documentation.
Our library adds a Swagger startup extension that, by default, adds custom Digipolis operator filters that follow the Digipolis API guidelines.

Table of Contents

• Target framework
• Installation
• Usage
• Custom options
• Contributing
• Support

Target framework

This package targets .NET Standard 2.1.

Installation

To add the library to a project, you add the package to the csproj file :

  <ItemGroup>
    <PackageReference Include="Digipolis.swagger" Version="1.0.7" />
  </ItemGroup>

In Visual Studio you can also use the NuGet Package Manager to do this.

Usage

This library serves as the Digipolis Swagger extensions library. It contains the service collection extension method to register the Digipolis Swagger options, to be called in the ConfigureServices method of the Startup class.

services.AddDigipolisSwagger(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "Your API title",
            Description = "Your API description",
            Version = "v1",
            Contact = new OpenApiContact
            {
                Email = "your.email@digipolis.be",
                Name = "Your name"
            },
            License = new OpenApiLicense
            {
                Name = "None",
                Url = null,
            },
        });
    });

This method adds basic operator filters that abide the rules set by the Digipolis API guidelines. Make sure to fill in the SwaggerDoc option as this one is not automatically set.

In the Configure method of the Startup class you should also add the UseDigipolisSwagger middleware. Like this for example:

app.UseDigipolisSwagger();

You can also include a collection of versions if you need to include multiple version. To do this change the UseDigipolisSwagger to:

app.UseDigipolisSwagger(versionProvider.ApiVersionDescriptions.Select(a => a.GroupName));

Custom options

This library extends the original SwaggerGenOptions with additional default properties. If you wish to prevent certain default options to be added simply set these options to false, or if you do want them to be added simple set them to true (if they are not yet true by default).

services.AddDigipolisSwagger(options =>
    {
        options.DefaultAddAuthorizationHeaderRequired = false;
    });

Here is a complete overview of the additional options to be set:

Option	Description	Default
DefaultComments	When set to true the xml documents will be added.	true
DefaultSecurityDefinition	When set to true and when the SwaggerGeneratorOptions.SecuritySchemes have no elements with key 'Bearer' then the default JWT authoriztion header security scheme is added.	true
DefaultSchemaIdSelector	When set to true the SchemaGeneratorOptions.SchemaIdSelector will be set to the SchemaIdSelector when this option is not set with a different schemaId Selector function	true
DefaultAddAuthorizationHeaderRequired	When set to true the AddAuthorizationHeaderRequired class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultRemoveSyncRootParameter	When set to true the RemoveSyncRootParameter class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultLowerCaseQueryParameterFilter	When set to true the LowerCaseQueryParameterFilter class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultCamelCaseBodyParameterFilter	When set to true the CamelCaseBodyParameterFilter class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultAddDefaultValues	When set to true the AddDefaultValues class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultAddPagingParameterDescriptions	When set to true the AddPagingParameterDescriptions class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultSetDescription	When set to true the SetDescription class will be added to the OperationFilterDescriptors list by default if not yet included.	true
DefaultAddCorrelationHeaderRequired	When set to true the AddCorrelationHeaderRequired class will be added to the OperationFilterDescriptors list by default if not yet included	true

Contributing

Pull requests are always welcome, however keep the following things in mind:

• New features (both breaking and non-breaking) should always be discussed with the repo's owner. If possible, please open an issue first to discuss what you would like to change.
• Fork this repo and issue your fix or new feature via a pull request.
• Please make sure to update tests as appropriate. Also check possible linting errors and update the CHANGELOG if applicable.

Support

Rob Liekens (rob.liekens@digipolis.be)