Enhancing NSwag with External Assembly Type Mappers for OpenAPI Document Generation

[paolov]

Hello!

I work with a diverse technology stack, managing multiple microservices built in .NET, Java, and Node.js. Our goal is to automate OpenAPI document generation as part of our CI/CD pipeline, keeping our process efficient and our artifacts lean. In our journey, we've encountered a specific challenge with NSwag in the .NET ecosystem that we believe could be an opportunity for a valuable enhancement.

The Challenge
Our current setup involves running NSwag as a task during MSBuild, leveraging a JSON configuration file to generate the OpenAPI document automatically. This approach has worked well for our Java and Node.js services, allowing us to generate and store OpenAPI documents in a central repository without introducing external dependencies or configurations directly into the project.

However, we've hit a roadblock with our .NET services. While we successfully created our IDocumentProcessor in a separate assembly, which NSwag loads correctly, we're struggling with the need to define numerous ITypeMappers for complex objects that are unique to an external library we use. These objects, due to their custom serialization implementation, cannot be automatically handled by NJsonSchema and, thus, require custom mapping.

The crux of the issue is the apparent lack of a way to specify these type mappers via the configuration file, similar to how we can with document processors. Our workaround—using the document provider option—forces us to add unnecessary dependencies to each project, contradicting our objective to keep our microservices clean and lean.

Proposed Solution
I propose an enhancement to NSwag that introduces a mechanism to specify custom type mappers (and potentially other settings) through external configuration, similar to how document and operation processors are specified. This could be achieved by extending the NSwag.Commands.OpenApiGeneratorCommandBase to include an interface or another extension point that allows for dynamic modification of settings based on external input.

Example Interface Proposal:

interface ICustomTypeMapperProvider
{
    IEnumerable<ITypeMapper> GetMappers();
}

Or a more generic one

interface ICustomConfiguration
{
    void Configure(AspNetCoreOpenApiDocumentGeneratorSettings settings); //or TSetting but could be more challenging
}

Benefits:

• Streamlined Configuration: Simplifies the setup for generating OpenAPI documents across multiple services, especially in microservices architectures.
• Cleaner Build Artifacts: Eliminates the need to include NSwag and related dependencies in the final binaries of each service.
• Greater Flexibility: Offers enhanced flexibility in handling complex types that require custom serialization, crucial for working with diverse and complex technology stacks.

Why This Matters
In our infrastructure, automated and lean generation of OpenAPI documents is crucial. It ensures that as we scale and add new services, our documentation remains up-to-date without manual intervention. Moreover, by avoiding unnecessary dependencies, we maintain clean build artifacts, which is essential for microservice efficiency and hygiene.

This feature could greatly benefit not just our projects but also the broader NSwag community, especially those dealing with similar challenges in microservices environments.

Seeking Feedback
I'm eager to hear your thoughts on this proposal. Your feedback, experiences, and any insights into similar challenges or needs within your projects would be invaluable. Together, I believe we can enhance NSwag to better serve our evolving development practices.

Thank you for considering this enhancement.

Best regards,

Paolo