OpenAPI/Swagger Source Generator for C# Azure Functions

A zero-code basic OpenAPI (Swagger) generator for C# Azure Functions.

Usage

Just install the package and run the app. By default, you will get an endpoint openapi that returns the Swagger UI for browing your API, as well as an endpoint with the standard swagger.json file. The generated swagger file will contain all HTTP-triggered functions in the compilation.

This assumes the routePrefix has been configured as empty (to override the default of /api) in host.json:

{
  ...
  "extensions": {
    "http": {
      "routePrefix": ""
    }
  }
}

Opening the openapi endpoint renders the SwaggerUI:

The generated swagger.json can be inspected in the project’s intermediate output path (by default, obj\Debug\[TFM]\openapi\v2\swagger.json).

The swagger.json as well as the function endpoints are generated at build-time by a C# source generator. As such, you can inspect the generated code by setting the EmitCompilerGeneratedFiles project property to true like:

  <PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  </PropertyGroup>

This will emit the generated functions source files under $(IntermediateOutputPath)\generated\Devlooped.Azure.Functions.OpenApi\SourceGenerator:

Customization

There are several ways of customizing the generation, all driven by MSBuild.

The main generation driver is an MSBuild item OpenApi, which contains various pieces of metadata to tweak the output. Its item definition is as follows:

  <ItemDefinitionGroup>
    <OpenApi>
      <Title />
      <Description />
      <Version />
      <Route />
      <Url />
      <SchemaVersion>2</SchemaVersion>
    </OpenApi>
  </ItemDefinitionGroup>

If no <OpenApi Include=".."> is provided, one is automatically added, with the default values applied.

The default values are:

• Title: first with a non-empty value from $(AssemblyTitle), $(Product), $(ProductName), $(Title).
• Description: $(Description)
• Version: first with non-empty value from $(Version), $(InformationalVersion), $(AssemblyVersion)
• Route: /openapi/v%(SchemaVersion)/swagger.json, with SchemaVersion being 2 by default.
• Url: /api or extensions.http.routePrefix in host.json if set to a non-empty value, / otherwise.

Dogfooding

We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced.

The CI feed is https://pkg.kzu.io/index.json.

The versioning scheme for packages is:

• PR builds: 42.42.42-pr[NUMBER]
• Branch builds: 42.42.42-[BRANCH].[COMMITS]

Sponsors

get mentioned here too!