C# Swashbuckle Swagger partial API documentation

1
votes

I have a Web API project with tons of services. Initially we used standard API documentation that comes out-of-the-box with ASP.NET.

Now I want to migrate our documentation to Swagger. I use Swashbuckle. I got some very specific issues with the documentation that I don't want to describe.

That said and also because I want to keep my swagger docs clean and high quality I want to find a way to add APIs to swagger one by one.

So, the main question: Can I migrate to swagger adding new APIs to the documentation gradually and keeping my old docs untouched?

2
asp.net-mvcasp.net-web-apiswaggerswagger-uiswashbuckle
From what I've seen in my use of Swashbuckle, you can't migrate individual APIs. But in my experience, once you start moving your documentation to Swagger, you won't miss the old MVC style documentation. - MichaelDotKnox

2 Answers

0
votes

You can use the ApiExplorerSettingsAttribute on controllers and methods you do not want to appear in the Swagger documentation as documented here. I guess the out-of-the-box documentation can be controlled in a similar way (I don't have any experience on this part). Combining these two features allows you to move documentation gradually to Swagger.

0
votes

You can use the [Obsolete()] attribute to hide methods from Swashbuckle. First you need to configure your Swashbuckle to look for this attribute as it builds the Swagger document:

config.EnableSwagger(
    routePrefix + "docs/{apiVersion}/swagger",
    c =>
    {
        // Set this flag to omit descriptions for any actions decorated with the Obsolete attribute
        c.IgnoreObsoleteActions();
        // Set this flag to omit schema property descriptions for any type properties decorated with the
        c.IgnoreObsoleteProperties();
    });

Then decorate the actions you want hidden:

[Obsolete("Hidden from Swashbuckle during renovations")]
[HttpGet]
Task<object> async WhyILostMyJob(string query)
{
     return await Database.SqlExecAsync(query, isAdmin: true);
}

Note that this only hides the method, it is still callable. If you want to take it to the next step you'll need to introduce an authentication or authorization filter.