Welcome to Software Development on Codidact!
Will you help us build our independent community of developers helping developers? We're small and trying to grow. We welcome questions about all aspects of software development, from design to code to QA and more. Got questions? Got answers? Got code you'd like someone to review? Please join us.
Best practices for company internal Swagger Docs in production
The current project I am working on consists of a bunch of microservices (Web APIs) accessible only internally using Entra ID (formerly Azure ID).
To simplify the development, all services expose Swagger Docs, but our SRE told us that Swagger Docs should be disabled in production.
I understand the risks of publicly exposing Swagger Docs in production (increased attack surface, information exposure, unauthorized access risks), but I think none of these apply to the case of having an internal Swagger Docs:
- access is limited to internal users
- non-prod Swagger Docs is accessible. That means that even with Prod Swagger Docs disabled, anyone with prod access can use a bearer token and Postman (or similar) to call an accessible endpoint
Does disabling Swagger Docs for the production environment make sense when all endpoints are accessible internally only?
1 answer
Disabling Swagger docs is a terrible idea even for a public API. Swagger saves the consumer an enormous amount of development and testing. We're talking weeks or months of work done in seconds, with far less opportunity for human error than a hand-coded client. Swagger is so valuable that if you don't publish Swagger docs for your API, you don't have a minimum viable product.
Also note that your title differs from your question body. Swagger docs and the Swagger UI are different things. My answer applies to your question body.
1 comment thread