OpenAPIPlus 1.0.0

OpenAPI Plus

An enhanced OpenAPI/Swagger documentation generator for ASP.NET Core that automatically extracts and applies XML documentation comments to API parameters, including nested properties in complex objects.

Features

• ✅ Automatic Parameter Descriptions: Extracts descriptions from XML comments and applies them to OpenAPI schema
• ✅ GET Request Support: Adds descriptions to query parameters and route parameters
• ✅ POST/PUT Request Support: Adds detailed descriptions to JSON body parameters, including nested properties
• ✅ Form Parameter Support: Applies descriptions to form parameters
• ✅ Nested Property Descriptions: Automatically includes descriptions for inner properties of complex objects
• ✅ Type Information: Includes parameter types, validation rules, and constraints in documentation

Installation

1. Add the OpenAPIGenerator project reference to your API project
2. Configure Swagger in your Program.cs:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new()
    {
        Title = "Sample API",
        Version = "v1",
        Description = "Sample API for testing OpenAPI DescriptionFilter extensions"
    });
    
    // Include XML comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    if (File.Exists(xmlPath))
    {
        c.IncludeXmlComments(xmlPath);
    }
    
    // Add the DescriptionFilter
    c.OperationFilter<DescriptionFilter>();
});

3. Enable XML documentation generation in your .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Usage

Documenting GET Endpoints

For GET requests, add XML comments to your controller methods and parameters:

/// <summary>
/// Retrieves a list of users with optional filtering and pagination parameters.
/// </summary>
/// <param name="pageNumber">The page number for pagination. Must be greater than 0. Default is 1.</param>
/// <param name="pageSize">The number of items per page. Must be between 1 and 100. Default is 10.</param>
/// <param name="isActive">Optional filter to return only active or inactive users.</param>
[HttpGet("users")]
public IActionResult GetUsers([FromQuery] int pageNumber = 1, [FromQuery] int pageSize = 10, [FromQuery] bool? isActive = null)
{
    // Implementation
}

Result in Swagger UI:

Documenting POST/PUT Endpoints with Complex Objects

For POST and PUT requests, document your complex object parameters and their nested properties:

/// <summary>
/// Creates a new user in the system.
/// </summary>
/// <param name="user">The user object containing all necessary information to create a new user.</param>
[HttpPost("users")]
public IActionResult CreateUser([FromBody] User user)
{
    // Implementation
}

Document your model classes with XML comments:

public class User
{
    /// <summary>
    /// Gets or sets the user's first name. This field is required and must be between 2 and 50 characters.
    /// </summary>
    public string FirstName { get; set; } = string.Empty;

    /// <summary>
    /// Gets or sets the metadata information associated with this user.
    /// </summary>
    public Metadata? Metadata { get; set; }
}

public class Metadata
{
    /// <summary>
    /// Gets or sets the version number of the metadata. This is used for tracking changes over time.
    /// </summary>
    public int Version { get; set; }

    /// <summary>
    /// Gets or sets the creation timestamp when this metadata was first created. Format: ISO 8601.
    /// </summary>
    public DateTime CreatedTimestamp { get; set; }
}

Result in Swagger UI:


Result in Postman:

The descriptions are automatically included in the OpenAPI schema, which Postman imports:

How It Works

The DescriptionFilter implements IOperationFilter and processes OpenAPI operations:

• For GET/Other Requests: Extracts method and parameter descriptions from XML comments and applies them to query/route parameters
• For POST/PUT Requests:
  • Builds a comprehensive description tree from XML comments
  • Applies descriptions to JSON schema properties, including nested objects
  • Handles form parameters with their descriptions

Project Structure

OpenAPIPlus/
├── OpenAPIGenerator/          # Core library
│   ├── DescriptionFilter.cs   # Main operation filter
│   ├── OpenApiOperationExtention.cs
│   ├── ControllerActionDescriptorExtention.cs
│   └── Models/                # Internal models
└── Test.SampleAPI/            # Sample API for testing
    ├── Controllers/
    ├── Models/
    └── Program.cs

Requirements

• .NET 8.0 or later
• ASP.NET Core
• Swashbuckle.AspNetCore (Swagger/OpenAPI)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.