A zero-code basic OpenAPI (Swagger) generator for C# Azure Functions.
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
:
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
, withSchemaVersion
being2
by default.Url
:/api
orextensions.http.routePrefix
inhost.json
if set to a non-empty value,/
otherwise.
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]