- Notifications
You must be signed in to change notification settings - Fork710
API Documentation
Adding documentation is often the final, pivotal step in making your versioned services available to clients and fosters their utilization. While there are many approaches to documenting your services, OpenAPI (formerly Swagger) has quickly become the de facto method for describing REST services.
The ASP.NET API versioning project provides several new API explorer implementations that make it easy to add versioning into your OpenAPI configurations. Each of these API explorers do all of the heavy lifting to discover and collate your REST services by API version. They do not directly rely on nor use any external OpenAPI libraries so that you can use them for other scenarios as well.
Any OpenAPI generator such as NSwag or Swashbuckle that uses the API Explorer can be used; however, most examples use Swashbuckle for historical reasons.
Everything you need to add versioned documentation to your API controllers.
config.AddApiVersioning();// format the version as "'v'major[.minor][-status]"varapiExplorer=config.AddVersionedApiExplorer( o=>o.GroupNameFormat="'v'VVV");config.EnableSwagger("{apiVersion}/swagger", swagger=>{swagger.MultipleApiVersions((apiDescription,version)=>apiDescription.GetGroupName()==version, info=>{foreach(vargroupinapiExplorer.ApiDescriptions){info.Version(group.Name,$"Example API{group.ApiVersion}");}});}).EnableSwaggerUi( swagger=>swagger.EnableDiscoveryUrlSelector());
Review theexample project for additional setup and configuration options.
Everything you need to add versioned documentation to your OData controllers.
configuration.AddApiVersioning();varmodelBuilder=newVersionedODataModelBuilder(configuration){ModelConfigurations={newMyModelConfiguration()}};configuration.MapVersionedODataRoutes("odata","api",modelBuilder);// format the version as "'v'major[.minor][-status]"varapiExplorer=configuration.AddODataApiExplorer( o=>o.GroupNameFormat="'v'VVV");configuration.EnableSwagger("{apiVersion}/swagger", swagger=>{swagger.MultipleApiVersions((apiDescription,version)=>apiDescription.GetGroupName()==version, info=>{foreach(vargroupinapiExplorer.ApiDescriptions){info.Version(group.Name,$"Example API{group.ApiVersion}");}});}).EnableSwaggerUi( swagger=>swagger.EnableDiscoveryUrlSelector());
Review the following example projects for additional setup and configuration options:
Note: This API explorer does not directly tie intoSwashbuckle with OData because that project also prescribes how API versioning is performed, which is incompatible with this project.
Everything you need to add versioned documentation to yourMinimal and controller-based APIs.
publicclassConfigureSwaggerOptions:IConfigureOptions<SwaggerGenOptions>{readonlyIApiVersionDescriptionProviderprovider;publicConfigureSwaggerOptions(IApiVersionDescriptionProviderprovider)=>this.provider=provider;publicvoidConfigure(SwaggerGenOptionsoptions){foreach(vardescriptioninprovider.ApiVersionDescriptions){options.SwaggerDoc(description.GroupName,newOpenApiInfo(){Title=$"Example API{description.ApiVersion}",Version=description.ApiVersion.ToString(),});}}}
varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddControllers();builder.Services.AddProblemDetails();builder.Services.AddEndpointsApiExplorer();builder.Services.AddApiVersioning().AddMvc()// ← bring in MVC (Core); not required for Minimal APIs.AddApiExplorer(// format the version as "'v'major[.minor][-status]" options=>options.GroupNameFormat="'v'VVV");services.AddTransient<IConfigureOptions<SwaggerGenOptions>,ConfigureSwaggerOptions>();services.AddSwaggerGen();varapp=builder.Build();app.UseSwagger();app.UseSwaggerUI( options=>{foreach(vardescriptioninapp.DescribeApiVersions()){varurl=$"/swagger/{description.GroupName}/swagger.json";varname=description.GroupName.ToUpperInvariant();options.SwaggerEndpoint(url,name);}});app.MapControllers();app.Run();
Review the following example projects for additional setup and configuration options:
Everything you need to add versioned documentation to your OData controllers.
publicclassConfigureSwaggerOptions:IConfigureOptions<SwaggerGenOptions>{readonlyIApiVersionDescriptionProviderprovider;publicConfigureSwaggerOptions(IApiVersionDescriptionProviderprovider)=>this.provider=provider;publicvoidConfigure(SwaggerGenOptionsoptions){foreach(vardescriptioninprovider.ApiVersionDescriptions){options.SwaggerDoc(description.GroupName,newOpenApiInfo(){Title=$"Example API{description.ApiVersion}",Version=description.ApiVersion.ToString(),});}}}
varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddControllers().AddOData();builder.Services.AddProblemDetails();builder.Services.AddEndpointsApiExplorer();builder.Services.AddApiVersioning().AddOData( options=>options.AddRouteComponents()).AddODataApiExplorer(// format the version as "'v'major[.minor][-status]" options=>options.GroupNameFormat="'v'VVV");services.AddTransient<IConfigureOptions<SwaggerGenOptions>,ConfigureSwaggerOptions>();services.AddSwaggerGen();varapp=builder.Build();app.UseSwagger();app.UseSwaggerUI( options=>{foreach(vardescriptioninapp.DescribeApiVersions()){varurl=$"/swagger/{description.GroupName}/swagger.json";varname=description.GroupName.ToUpperInvariant();options.SwaggerEndpoint(url,name);}});app.MapControllers();app.Run();
Review the following example projects for additional setup and configuration options:
- Home
- Quick Starts
- Version Format
- Version Discovery
- Version Policies
- How to Version Your Service
- API Versioning with OData
- Configuring Your Application
- Error Responses
- API Documentation
- Extensions and Customizations
- Known Limitations
- FAQ
- Examples