Added more functionality to the OpenAPI generation and ReDoc generation

[MarkusBernhardt]

Added OpenAPI Functionality

OpenApiIgnore Ignore this HttpFunction with all specified HttpMethods in all OpenAPI documents

http.HttpFunction<CreateCustomerHttpRequestDto>(HttpMethod.Post)
    .OpenApiIgnore()

InjectResource Inject a resource file into the via the openapi endpoint downloadable files. It is important that the resource file is configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .InjectResource(Assembly.GetExecutingAssembly(), "Resources.OpenApi.custom.txt")

InjectResources Inject all resource files from a given path into the via the openapi endpoint downloadable files. It is important that the resource files are configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .InjectResources(Assembly.GetExecutingAssembly(), "Resources.OpenApi.diagrams")

InjectJavaScript Inject a custom JavaScript into the displayed Swagger UI. It is important that the JavaScript file is configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .InjectJavaScript(Assembly.GetExecutingAssembly(), "Resources.OpenApi.console-log.js")

InjectStylesheet Inject a custom CSS into the displayed Swagger UI. It is important that the CSS file is configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .InjectStylesheet(Assembly.GetExecutingAssembly(), "Resources.OpenApi.theme-material.css")

InjectLogo Inject a custom logo into the displayed Swagger UI. It is important that the logo file is configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .InjectLogo(Assembly.GetExecutingAssembly(), "Resources.OpenApi.app-logo-small.svg")

AddSecurityScheme Enable the Swagger UI Authorize button.

builder
    .OpenApiEndpoint(openApi => openApi
        .AddSecurityScheme("Bearer", // Reference.Id of this security scheme
            new OpenApiSecurityScheme
            {
                Description = "JWT Authorization header using the Bearer scheme.",
                Type = SecuritySchemeType.Http, // We set the scheme type to http since we're using bearer authentication
                Scheme = "bearer" // The name of the HTTP Authorization scheme to be used in the Authorization header. In this case "bearer".
            }
        )

Support mulitple OpenAPI documents Title and Version are still supported in the OpenAPI configuration to define the default document, but are optional now. Additional documents can be added via AddOpenApiInfo. Via a combo box in the Swagger UI topbar the different OpenAPI documents can be selected.

builder
    .OpenApiEndpoint(openApi => openApi
        // openapi/openapi.yaml
        .Title("My API Title 2.0.0-beta-113")
        .Version("v2")

        // openapi/internal/openapi.yaml
        .AddOpenApiInfo("v2-internal", "internal/openapi.yaml", new OpenApiInfo
            {
                Title = "API intern 2.0.0-beta-113",
                Version = "v2",
                Description = "Upcoming API"
            }
        )

        // openapi/external/openapi.yaml
        .AddOpenApiInfo("v2-external", "external/openapi.yaml", new OpenApiInfo
            {
                Title = "API 2.0.0-beta-113",
                Version = "v2",
                Description = "Upcoming API"
            },
            new CustomOpenApiHttpFunctionFilter(),
            true
        )

Added ReDoc Documentation Generator

The ReDoc UI gets enabled like the Swagger UI

builder
    .OpenApiEndpoint(openApi => openApi
        .RedocUserInterface()

The ReDoc UI supports the same injects as the SwaggerUI:

• ReDocInjectLogo
• ReDocInjectResource
• ReDocInjectResources
• ReDocInjectStylesheet
• ReDocInjectJavaScript

ReDocAddDocumentFilter Changes to the openapi.yaml made by this DocumentFilter are only visible to the ReDoc UI.

builder
    .OpenApiEndpoint(openApi => openApi
        .ReDocAddDocumentFilter(() => new CustomRedocDocumentFilter())

ReDocInjectExtensions Inject all extensions (YAML) from a given path into the openapi.yaml visible to the ReDoc UI. It is important that the extensions are configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .ReDocInjectExtensions(Assembly.GetExecutingAssembly(), "Resources.ReDoc.extensions")

ReDocInjectTags Inject all tags (YAML) from a given path into the openapi.yaml visible to the ReDoc UI. The description of an OpenAPI tag can be optionally imported from separate markup file (MD). This greatly helps formatting the content correctly. It is important that the tags are configured as EmbeddedResource in Visual Studio.

builder
    .OpenApiEndpoint(openApi => openApi
        .ReDocInjectTags(Assembly.GetExecutingAssembly(), "Resources.ReDoc.tags")

Small Fixes

Handle file content as byte[] not string OpenApiOutputModel was handling the Content as string. This is problematic, as this leads to a character conversion (UTF-8) when reading the file into the string. This breaks binary content like images.

Example

I added an example project under Scratch/OpenApi. This project is still in "Debug" mode. To run it do the following:

• Rebuild Scratch/OpenApi
• Execute FunctionMonkey.Compiler
• Execute Scratch/OpenApi

How we use it

If you want you can have a look at our sandbox, how we are using this in our upcoming API. Still work in progress: https://sepaexpress-sand-fx.azurewebsites.net/openapi https://sepaexpress-sand-fx.azurewebsites.net/redoc