AzureExtensions.Swashbuckle
4.0.0-beta
See the version list below for details.
dotnet add package AzureExtensions.Swashbuckle --version 4.0.0-beta
NuGet\Install-Package AzureExtensions.Swashbuckle -Version 4.0.0-beta
<PackageReference Include="AzureExtensions.Swashbuckle" Version="4.0.0-beta" />
paket add AzureExtensions.Swashbuckle --version 4.0.0-beta
#r "nuget: AzureExtensions.Swashbuckle, 4.0.0-beta"
// Install AzureExtensions.Swashbuckle as a Cake Addin
#addin nuget:?package=AzureExtensions.Swashbuckle&version=4.0.0-beta&prerelease
// Install AzureExtensions.Swashbuckle as a Cake Tool
#tool nuget:?package=AzureExtensions.Swashbuckle&version=4.0.0-beta&prerelease
AzureExtensions.Swashbuckle
OpenAPI 2/3 implementation based on Swashbuckle(Swagger) tooling for API's built with Azure Functions
This product aims to easily provide Swagger and Swagger UI of APIs created in Azure Functions
4.0.0-beta
- just remebering what the heck is going om here
- Updated to v4 Functions
- Updated to .NET 8
- Updated to isolated worker model (from now on it is going to be the only one that is supported, as inprocess is going to be deprecated)
- Updated to UI v5.17.3
- Updated to Swagger 5.6.5
- Updated docs
- Considering removing support of NewtonJson
3.3.1-beta
- #64 Support for authorization configuration
- #60 Consolidated extensions and added one to support .net 5
- Updated docs
- Updated js/html/css libs
- Some classed made public to support 3-party IoC.
- Fixed several issues, related to versioning and XML comments.
- Updated to UI v3.37.2
- Updated to Swagger 5.6.3
- Updated documentation
- Ability to create multiple versions of documents, example added.
- Added examples of a custom filter, improved test application
https://www.nuget.org/packages/AzureExtensions.Swashbuckle/3.3.1-beta
3.1.6
https://www.nuget.org/packages/AzureExtensions.Swashbuckle/3.1.6
Fixed #8, #9
Updated to UI v3.25.1
Updated to Swagger 5.4.1
Fixed base url for Swagger UI
Breaking:
Option and DocumentOption renamed to SwaggerDocOptions and SwaggerDocument respectivly and moved to AzureFunctions.Extensions.Swashbuckle.Settings namespace
Properties renamed:
PrepandOperationWithRoutePrefix ⇒ PrependOperationWithRoutePrefix
AddCodeParamater ⇒ AddCodeParameter
Properties added:
Added ability to configure SwaggerGen via ConfigureSwaggerGen
Added ability to override default url to Swagger json document (in case of reverse proxy/gateway/ingress) are used.
Size:
All the resources are places in zip archive in order to decrease result dll size by 338% (from 1.594kb to 472kb)
3.0.0
- Updated to v3 Functions
- Updated to 5.0.0 Swashbuckle.AspNetCore nugets
- Merged PRs to fix issues related to RequestBodyType and Ignore attribute
- application/json is a default media type.
Sample
Update
Version 3.0.0
Getting Started
- Install the standard Nuget package into your Azure Functions application.
Package Manager : Install-Package AzureExtensions.Swashbuckle
CLI : dotnet add package AzureExtensions.Swashbuckle
- Add Program.cs class on your Functions project.
!!! Now you need to specify in option the RoutePrefix.
opts.RoutePrefix = "api";
using System;
using System.Collections.Generic;
using Microsoft.Extensions.Hosting;
using System.Reflection;
using AzureFunctions.Extensions.Swashbuckle.Settings;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi;
using Microsoft.OpenApi.Models;
using AzureFunctions.Extensions.Swashbuckle;
using Swashbuckle.AspNetCore.SwaggerGen;
var host = new HostBuilder()
.ConfigureServices((hostContext, services) =>
{
//Register the extension
services.AddSwashBuckle(opts =>
{
// If you want to add Newtonsoft support insert next line
// opts.AddNewtonsoftSupport = true;
opts.RoutePrefix = "api";
opts.SpecVersion = OpenApiSpecVersion.OpenApi3_0;
opts.AddCodeParameter = true;
opts.PrependOperationWithRoutePrefix = true;
opts.XmlPath = "TestFunction.xml";
opts.Documents = new[]
{
new SwaggerDocument
{
Name = "v1",
Title = "Swagger document",
Description = "Swagger test document",
Version = "v2"
},
new SwaggerDocument
{
Name = "v2",
Title = "Swagger document 2",
Description = "Swagger test document 2",
Version = "v2"
}
};
opts.Title = "Swagger Test";
//opts.OverridenPathToSwaggerJson = new Uri("http://localhost:7071/api/Swagger/json");
opts.ConfigureSwaggerGen = x =>
{
//custom operation example
x.CustomOperationIds(apiDesc => apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)
? methodInfo.Name
: new Guid().ToString());
//custom filter example
//x.DocumentFilter<RemoveSchemasFilter>();
//oauth2
x.AddSecurityDefinition("oauth2",
new OpenApiSecurityScheme
{
Type = SecuritySchemeType.OAuth2,
Flows = new OpenApiOAuthFlows
{
Implicit = new OpenApiOAuthFlow
{
AuthorizationUrl = new Uri("https://your.idserver.net/connect/authorize"),
Scopes = new Dictionary<string, string>
{
{ "api.read", "Access read operations" },
{ "api.write", "Access write operations" }
}
}
}
});
};
// set up your client ID if your API is protected
opts.ClientId = "your.client.id";
opts.OAuth2RedirectPath = "http://localhost:7071/api/swagger/oauth2-redirect";
});
})
.Build();
host.Run();
- Add swagger and swagger ui endpoint functions on your project.
public class SwaggerController
{
private readonly ISwashBuckleClient swashBuckleClient;
public SwaggerController(ISwashBuckleClient swashBuckleClient)
{
this.swashBuckleClient = swashBuckleClient;
}
[SwaggerIgnore]
[Function("SwaggerJson")]
public async Task<HttpResponseData> SwaggerJson(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "Swagger/json")]
HttpRequestData req)
{
return await this.swashBuckleClient.CreateSwaggerJsonDocumentResponse(req);
}
[SwaggerIgnore]
[Function("SwaggerYaml")]
public async Task<HttpResponseData> SwaggerYaml(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "Swagger/yaml")]
HttpRequestData req)
{
return await this.swashBuckleClient.CreateSwaggerYamlDocumentResponse(req);
}
[SwaggerIgnore]
[Function("SwaggerUi")]
public async Task<HttpResponseData> SwaggerUi(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "Swagger/ui")]
HttpRequestData req)
{
return await this.swashBuckleClient.CreateSwaggerUIResponse(req, "swagger/json");
}
/// <summary>
/// This is only needed for OAuth2 client. This redirecting document is normally served
/// as a static content. Functions don't provide this out of the box, so we serve it here.
/// Don't forget to set OAuth2RedirectPath configuration option to reflect this route.
/// </summary>
/// <param name="req"></param>
/// <param name="swashBuckleClient"></param>
/// <returns></returns>
[SwaggerIgnore]
[Function("SwaggerOAuth2Redirect")]
public async Task<HttpResponseData> SwaggerOAuth2Redirect(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger/oauth2-redirect")]
HttpRequestData req)
{
return await this.swashBuckleClient.CreateSwaggerOAuth2RedirectResponse(req);
}
}
- Open Swagger UI URL in your browser.
If you does not changed api route prefix. Swagger UI URL is https://hostname/api/swagger/ui .
Options
Include Xml document file
AzureFunctions.Extensions.Swashbuckle can include xml document file.
Change your functions project's GenerateDocumentationFile option to enable.
builder.AddSwashBuckle(Assembly.GetExecutingAssembly(), opts => { opts.XmlPath = "TestFunction.xml"; });
Add configration setting this extensions on your functions project's local.settings.json
"SwaggerDocOptions": {
"XmlPath": "TestFunction.xml"
}
Alternatively you can add this section to your host.json
"extensions": {
"Swashbuckle": {
"XmlPath": "TestFunction.xml"
}
}
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Microsoft.ApplicationInsights.WorkerService (>= 2.22.0)
- Microsoft.Azure.Functions.Worker.ApplicationInsights (>= 1.2.0)
- Microsoft.Azure.Functions.Worker.Extensions.Abstractions (>= 1.3.0)
- Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore (>= 1.2.1)
- Swashbuckle.AspNetCore (>= 6.5.0)
- Swashbuckle.AspNetCore.Newtonsoft (>= 6.5.0)
- Swashbuckle.AspNetCore.Swagger (>= 6.5.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on AzureExtensions.Swashbuckle:
Package | Downloads |
---|---|
Service.Extensions.Functions
Extensions to provide consistent configurations and patterns for your service. |
|
Nebularium.Cthulhu.Swagger
Biblioteca para utilização em projetos Azure Functions expond uri do swagger. |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on AzureExtensions.Swashbuckle:
Repository | Stars |
---|---|
Azure-Samples/saga-orchestration-serverless
An orchestration-based saga implementation reference in a serverless architecture
|
Version | Downloads | Last updated |
---|---|---|
4.0.3 | 124 | 5/24/2024 |
4.0.2 | 816 | 5/15/2024 |
4.0.1 | 1,419 | 5/2/2024 |
4.0.0-beta | 51 | 5/1/2024 |
3.3.2 | 1,461,864 | 3/24/2021 |
3.3.1-beta | 9,578 | 2/2/2021 |
3.3.0-beta | 7,763 | 12/8/2020 |
3.2.2 | 640,107 | 6/17/2020 |
3.2.1-beta | 1,208 | 6/9/2020 |
3.2.0-beta | 1,272 | 6/4/2020 |
3.1.6 | 79,654 | 5/10/2020 |
3.1.5-beta | 1,163 | 5/3/2020 |
3.1.2-beta | 7,598 | 4/14/2020 |
3.1.1-beta | 852 | 4/13/2020 |
3.1.0-beta | 837 | 4/13/2020 |
3.0.2 | 88,547 | 2/29/2020 |
3.0.1 | 1,366 | 2/29/2020 |
3.0.0 | 6,440 | 2/24/2020 |
2.0.2 | 1,139 | 2/24/2020 |
2.0.1 | 3,844 | 12/28/2019 |
2.0.0 | 1,305 | 12/28/2019 |