Swagger Document With Code

This works with @domaindrivendev Swashbuckle.AspNetCore

This is a fork of Document Code With Code

If your philosophy about documentation align with that view, then use DalSoft.Swagger.DocumentCodeWithCode instead.

Why?

The code here is to embellish your Web API Swagger documentation using code via attributes:

• You can provide detailed and contextual request or response examples
• You can workaround providing multiple request or response examples (domaindrivendev/Swashbuckle.AspNetCore#228 and domaindrivendev/Swashbuckle.WebApi#397)

Getting Started

Install the Swashbuckle.AspNetCore package and configure as normal.

Install the Carable.Swashbuckle.AspNetCore.DocumentWithCode package using NuGet.

PM> Install-Package Carable.Swashbuckle.AspNetCore.DocumentWithCode

Modify startup.cs to include the OperationFilter.

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddSwaggerGen(options =>
    {
        ...
        options.OperationFilter<DocumentationAttributesOperationFilter>();
    });
}

Providing Documenation using Code

Inherit the BaseDocumentOperation. Now you can you document by setting the properties.

public class AddPetAttribute : BaseDocumentOperationAttribute
{
    public override void Apply(Operation operation, ISchemaRegistry schemaRegistry) 
    {
        operation.Summary = "Add a new pet to the store";
        operation.Description = "Pet object that needs to be added to the store";
    }
}

Providing Examples using Code

Use the the extension AddExampleToParameter and AddOrUpdate to provide request and response examples.

public class AddPetAttribute : BaseDocumentOperationAttribute
{
    public override void Apply(Operation operation, ISchemaRegistry schemaRegistry)
    {
    	operation.Parameters.Single(p=>p.Name=="pet").AddExampleToParameter(schemaRegistry, operation.OperationId, 
        	new Pet { Id = 1, Name = "doggie", Status = "available" });
        
        var exampleResponse = new Pet[] { new Pet { Id = 1, Name = "doggie", Status = "available" } };        
        operation.Responses.AddOrUpdate(schemaRegistry, operation.OperationId, "200", new Response
        {
            Description = "success"
        }, example:exampleResponse);
    }
}