This is a short and sweet post. And the title summarizes it well enough. Always Swagger Your API.
I can almost hear it now
I never use Swagger because (...)
And let me say, right now. I'll likely address that.
Whenever you are starting a new API, use swagger. I can't recall the documentation, design, and development challenges I've faced because a parameter was slightly mistyped, a class was mis-defined, a class was a slightly different shape, or I had a API call as a GET when I needed and expected it to be a POST.
Swagger solves this. When you need to create an API, being able to rapidly test it, develop against it, and document it saves hours for every minute it takes to implement it.
Reasons you might not want to use it:
- It can get very large, and slow
- It can expose endpoints (generally touted as a security risk)
- Something else to maintain
Too Large
For it becoming large: This is true. And I have two solutions.
a. It can be split, although it creates additional maintenance.
b. Get rid of Swagger after the rough, cowboy days of getting the API up and functional. I think every new API should have swagger through early development. Not necessarily forever.
Security - Exposed endpoints
First, this is a terrible argument from a security standpoint. The bad guys that you should worry about will have better tools to do what they do, including finding your endpoints.
There are real reasons to not want to expose the endpoints however. Perhaps you don't want a user a accident discover the page and create confusion. Or perhaps some calls are not documented on purpose (v2 over v1 endpoints).
Maintenance
You might just not want to deal with maintenance forever. If the swagger gets too large, or your targeting framework changes.
Remove Swagger
I'll say it one last time: Every new API should use Swagger, but when the API is mature enough feel free to remove it
Top comments (0)