aspnet-api-versioning VS Swashbuckle.AspNetCore

- The DTOs on the server should generally not change without warning. A deprecation cycle should ideally be in place so consumers can keep up over time and front end development doesn't have to be lock-step with the services the consume. Ideally some period of time between service v1 being deprecated and service v2 being required to allow consumers to react ( in this case, you're the consumer, so be kind to yourself ). Deets: https://github.com/dotnet/aspnet-api-versioning

This API versioning can be parameterized with some options, including the default version or even how the versioning will be done, whether by URL, header or media type. For more details, you can access the official documentation.

A lista completa pode ser vista aqui: https://github.com/microsoft/aspnet-api-versioning/wiki/Version-Format

Check out the official API versioning Github repository to find out more information.

Swashbuckle Github repo

Swashbuckle Swagger

That’s exactly what I meant. There’s about 0 maintenance required most of the time. Take a look at their official nuget GitHub page. This should work out of the box with ASP.NET core 3.0 and greater. For 5.0 onwards, the MVC template comes pre-configured with it.

When you run your web api app, you can access the swagger.json at http://localhost:/swagger/v1/swagger.json. Now either you can pass the link to swagger.json or make it accessible from file system. If you go the former route then you need to ensure your web api is up somewhere and updated or spin it up locally. I went ahead with downloading the file into file system using Swashbuckle.AspNetCore.Cli which can generate swagger.json from your web api assembly.

/// /// Represents the Swagger/Swashbuckle operation filter used to document the implicit API version parameter. /// /// This is only required due to bugs in the . /// Once they are fixed and published, this class can be removed. public class SwaggerDefaultValues : IOperationFilter { /// /// Applies the filter to the specified operation using the given context. /// /// The operation to apply the filter to. /// The current operation filter context. public void Apply(OpenApiOperation operation, OperationFilterContext context) { var apiDescription = context.ApiDescription; operation.Deprecated |= apiDescription.IsDeprecated(); // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1752#issue-663991077 foreach (var responseType in context.ApiDescription.SupportedResponseTypes) { // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/b7cf75e7905050305b115dd96640ddd6e74c7ac9/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L383-L387 var responseKey = responseType.IsDefaultResponse ? "default" : responseType.StatusCode.ToString(); var response = operation.Responses[responseKey]; foreach (var contentType in response.Content.Keys) if (responseType.ApiResponseFormats.All(x => x.MediaType != contentType)) response.Content.Remove(contentType); } if (operation.Parameters == null) return; // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/412 // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/413 foreach (var parameter in operation.Parameters) { var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name); parameter.Description ??= description.ModelMetadata.Description; if (parameter.Schema.Default == null && description.DefaultValue != null) { // REF: https://github.com/Microsoft/aspnet-api-versioning/issues/429#issuecomment-605402330 var json = JsonSerializer.Serialize(description.DefaultValue, description.ModelMetadata.ModelType); parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json); } parameter.Required |= description.IsRequired; } } }

domaindrivendev/Swashbuckle.AspNetCore

Swashbuckle.AspNetCore.Swagger

Now we'll focus on getting versioning working with Swagger Generation and Swashbuckle.