𝗘𝘅𝗽𝗹𝗼𝗿𝗶𝗻𝗴 𝗢𝗽𝗲𝗻𝗔𝗣𝗜 𝗖𝘂𝘀𝘁𝗼𝗺𝗶𝘇𝗮𝘁𝗶𝗼𝗻 𝗶𝗻 𝗔𝗦𝗣.𝗡𝗘𝗧 𝗖𝗼𝗿𝗲 𝗠𝗶𝗻𝗶𝗺𝗮𝗹 𝗔𝗣𝗜𝘀

Over the past few days, I’ve been working with 𝗢𝗽𝗲𝗻𝗔𝗣𝗜 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗶𝗻 𝗔𝗦𝗣.𝗡𝗘𝗧 𝗖𝗼𝗿𝗲, going beyond the basics of AddSwaggerGen() by using a more advanced and modular approach with AddOpenApi().

Key things I learned:

The difference between AddSwaggerGen() (Swashbuckle) and AddOpenApi() (OpenAPI.NET-based).
How to use 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁, 𝗢𝗽𝗲𝗿𝗮𝘁𝗶𝗼𝗻, 𝗮𝗻𝗱 𝗦𝗰𝗵𝗲𝗺𝗮 𝗧𝗿𝗮𝗻𝘀𝗳𝗼𝗿𝗺𝗲𝗿𝘀 to fully control the OpenAPI output.
Automatically adding security schemes, licensing info, and contact metadata using transformer methods.
How these tools help create clear, interactive API docs for clients or frontend teams.

𝘀𝗺𝗮𝗹𝗹 𝘀𝗻𝗶𝗽𝗽𝗲𝘁 :

builder.Services.AddOpenApi("v2", options => {
options.AddDocumentTransformer(new AddContactTransformer());
options.AddOperationTransformer();
options.AddDocumentTransformer((doc, ctx, token) => {
doc.Info.License = new OpenApiLicense { Name = "MIT" };
return Task.CompletedTask;
});
});

It’s been exciting to see how customizable and powerful OpenAPI can be when documenting minimal APIs properly.

If you're building public or internal APIs, I highly recommend exploring these transformers to give your documentation a professional edge!