Be.Vlaanderen.Basisregisters.AspNetCore.Swagger

Swagger and ReDoc helpers.

Goal

Provide an easy way to configure a project to use Swagger and have a nice API documentation out of the box.

Quick contributing guide

• Fork and clone locally.
• Build the solution with Visual Studio, build.cmd or build.sh.
• Create a topic specific branch in git. Add a nice feature in the code. Do not forget to add tests and/or docs.
• Run build.cmd or build.sh to make sure everything still compiles and all tests are still passing.
• When built, you'll find the binaries in ./dist which you can then test with locally, to ensure the bug or feature has been successfully fixed/implemented.
• Send a Pull Request.

Quick start

• Reference Be.Vlaanderen.Basisregisters.AspNetCore.Swagger, Be.Vlaanderen.Basisregisters.AspNetCore.Swagger.ReDoc or both.
• Have a look at the example Dummy.Api project.
• Browse to the root of your API.

Swagger

Features

• Read Swagger Request & Response examples from assembly.
• Describe enums as strings.
• Describe all enums and parameters in camel case.
• Support XML comments as documentation.
• Provide AutoRest support. (x-ms-enum)
• Provide GroupName as tags.
• Add 401 as possible response for endpoints which require authorization.
• Add 403 as possible response for endpoints which require authorization.
• Add (Auth) to endpoints which require authorization.

Usage

private static string GetApiLeadingText(ApiVersionDescription description)
    => $"Right now you are reading the documentation for version {description.ApiVersion} of the Example API{string.Format(description.IsDeprecated ? ", **this API version is not supported any more**." : ".")}";

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    // Configure other services here...

    // You most likely want these at least:
    // - AddMvcCore
    // - AddJsonFormatters
    // - AddJsonOptions
    // - AddApiExplorer
    // - AddVersionedApiExplorer
    // - AddApiVersioning

    services
      .AddLocalization()
      .AddSwagger<Startup>(new SwaggerOptions
      {
          ApiInfoFunc = (provider, description) => new Info
          {
              Version = description.ApiVersion.ToString(),
              Title = "Example API",
              Description = GetApiLeadingText(description),
              Contact = new Contact
              {
                  Name = "agentschap Digitaal Vlaanderen",
                  Email = "digitaal.vlaanderen@vlaanderen.be",
                  Url = "https://vlaanderen.be/informatie-vlaanderen"
              }
          },

          XmlCommentPaths = new [] { typeof(Startup).GetTypeInfo().Assembly.GetName().Name },

          AdditionalHeaderOperationFilters = new List<HeaderOperationFilter>
          {
              new HeaderOperationFilter("apiKey", "Optional API key for the request.")
          }
      });
}

ReDoc

Features

• Provide version 1.19.2 of ReDoc in an embedded way.
• Provide Flemish Government branding of ReDoc.
• Provide documentation for multiple versions.
• Provide C# client code. /clients/csharp
• Provide jQuery client code. /clients/jquery
• Provide AngularJS client code./clients/angularjs
• Provide Angular client code./clients/angular

Usage

public void Configure(
    IApplicationBuilder app,
    IApiVersionDescriptionProvider apiVersionProvider)
{
    app
       .UseSwaggerDocumentation(new SwaggerDocumentationOptions
        {
            ApiVersionDescriptionProvider = apiVersionProvider,
            DocumentTitleFunc = groupName => $"Example API {groupName}"
        })

        .UseMvc();
}

License

Massachusetts Institute of Technology (MIT)

Credits

Languages & Frameworks

• .NET Core - MIT
• .NET Core Runtime - CoreCLR is the runtime for .NET Core. It includes the garbage collector, JIT compiler, primitive data types and low-level classes. - MIT
• .NET Core APIs - CoreFX is the foundational class libraries for .NET Core. It includes types for collections, file systems, console, JSON, XML, async and many others. - MIT
• .NET Core SDK - Core functionality needed to create .NET Core projects, that is shared between Visual Studio and CLI. - MIT
• .NET Core Docker - Base Docker images for working with .NET Core and the .NET Core Tools. - MIT
• .NET Standard definition - The principles and definition of the .NET Standard. - MIT
• Roslyn and C# - The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs. - Apache License 2.0
• F# - The F# Compiler, Core Library & Tools - MIT
• F# and .NET Core - F# and .NET Core SDK working together. - MIT
• ASP.NET Core framework - ASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux. - Apache License 2.0

Libraries

• Newtonsoft.Json - Json.NET is a popular high-performance JSON framework for .NET - MIT
• Swashbuckle - Seamlessly adds a swagger to WebApi projects! - BSD
• Swashbuckle Filters - A bunch of useful filters for Swashbuckle.AspNetCore. - MIT
• ReDoc - 📘 OpenAPI/Swagger-generated API Reference Documentation. - MIT
• NSwag - The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript. - MIT

Tooling

• npm - A package manager for JavaScript. - Artistic License 2.0
• semantic-release - Fully automated version management and package publishing. - MIT
• semantic-release/changelog - Semantic-release plugin to create or update a changelog file. - MIT
• semantic-release/commit-analyzer - Semantic-release plugin to analyze commits with conventional-changelog. - MIT
• semantic-release/exec - Semantic-release plugin to execute custom shell commands. - MIT
• semantic-release/git - Semantic-release plugin to commit release assets to the project's git repository. - MIT
• semantic-release/npm - Semantic-release plugin to publish a npm package. - MIT
• semantic-release/github - Semantic-release plugin to publish a GitHub release. - MIT
• semantic-release/release-notes-generator - Semantic-release plugin to generate changelog content with conventional-changelog. - MIT
• commitlint - Lint commit messages. - MIT
• commitizen/cz-cli - The commitizen command line utility. - MIT
• commitizen/cz-conventional-changelog A commitizen adapter for the angular preset of conventional-changelog. - MIT

Flemish Government Libraries

• Be.Vlaanderen.Basisregisters.Build.Pipeline - Contains generic files for all Basisregisters pipelines. - MIT
• Be.Vlaanderen.Basisregisters.AspNetCore.Mvc.Formatters.Json - Default Json.NET serializer settings. - MIT