Validating API documentation with Swashbuckle and DotNet Core
Add a unit test to your program to assert that your documentation is complete
I’m a big fan of Swashbuckle, the DotNet library that automatically generates OpenAPI schema files and documentation for your project. When you’re working on a big project, though, I am often faced with a problem — someone adds a new API but forgets to document it.
One solution to this problem is to enable Visual Studio warning CS1591. On the other hand, CS1591 is very noisy. If you enable this warning, every class and every method will generate compiler warnings, not just the ones that need comments for Swashbuckle! Your developers will wind up adding lots of really silly small XMLDOC comments to classes that don’t need them.
An alternative approach is to add a unit test that validates our OpenAPI schema. It will verify that all methods, schemas, properties, and parameters all have documentation. With this approach, you can disable CS1591 and keep your code slightly cleaner while still being certain that your API documentation is complete.
Creating a TestServer for your Swashbuckle configuration
In DotNetCore, you can test your web host by using the TestServer class from Microsoft.AspNetCore.TestHost. It works by generating a simulated web server that acts like a Kestrel server but only works within your test suite.
How does the TestServer class know how your web server works? It depends on the ConfigureServices and Configure methods in your Startup class. What’s really odd is that TestServer doesn’t expect the class to implement an interface — it just hunts for those methods and fails if you don’t have them. Here’s one example:
Asserting the validity of your OpenAPI documentation
In my case I wanted to assert that all my methods, parameters, schemas, and properties all had description elements. Of course, once you’re examining your OpenAPI documentation you can enforce lots of rules. A few ideas that might be interesting:
- A method name must be less than 100 characters in length
- All API methods must have a wiki link in them
- Ensure method and class names match your standards such as PascalCase, camelCase, or snake_case.
You can do this of course by just iterating through the elements in your OpenAPI spec. Keep in mind that Swashbuckle allows you to have multiple Swagger files — Swagger being the original name for OpenAPI — and you may need to specify the correct name when calling GetSwagger():
With this test in place, as long as your pull requests execute unit tests, you’ll prevent any developers from accidentally creating a new API that lacks any of the necessary documentation.
Ted Spence heads engineering at ProjectManager.com and teaches at Bellevue College. If you’re interested in software engineering and business analysis, I’d love to hear from you on Mastodon or LinkedIn.
