Swagger only available in debug builds

[fgheysels]

Is there a reason why we only include swagger docs and swagger UI for debug-builds ?
When a new API is generated using the API template, the code that enables swagger is in #if DEBUG directives. Why should this not be included in release builds ? Does it expose a threat if we do ? To me, this is just API documentation which can be made public, but maybe that's just me :)

[tomkerkhove]

Some people tend to not use that for release because of security concerns for API discovery, but I do that anyway.

[stijnmoreels]

We see it more as a convenience for development and test environments, also across different teams, to have a better understanding. But not for production.

[fgheysels]

Well, that's an issue.
We build an artifact only once, and that same artifact is used in different environments (dev, test, prd). That's the only way to be sure that the component you've tested in test is identically the same as the one you're going to deploy into production.
So, either you create an artifact with a release config, and dev/test teams do not have access to open-api documentation, or you build an artifact in a debug-configuration and you deploy debug binaries to production ....

Next to that, do you then think that github, facebook, twillio, etc.... are at risk because they expose OpenApi documentation of their API's ?

[stijnmoreels]

Next to that, do you then think that github, facebook, twillio, etc.... are at risk because they expose OpenApi documentation of their API's ?

If I have a very paranoid day, yeah 😅😉. I actually think that evey information you can prevent from showing, is a good thing. Like you hide certain system info, version number.. and yes, also the blueprint of your application. But, again, that's maybe my paranoia. I do think that by exposing too much of this is increasing the risk. Bc otherwise you'll have to use a web crawler and lot of reconnaissance, and now you know exactly what data types are being used, what limits they have, what possible threshold cases the team has possibly missed...

But we're talking in the context of Arcus, so like Tom said, we chose a secure-by-default approach here. Nothing stops you from changing anything afterwards, the templates we provide only provide a starting point.

[tomkerkhove]

I don't agree with Stijn but don't want to force a change since it's a template and think people are knowledgeable to remove it, but our docs should be better to avoid wasting your time.

This is a case of better safe than sorry, although I don't see much of a risk personally but I also get Stijn his point for API discovery which is possible out-of-the-box.

[fgheysels]

So, we keep it like it is, but should we mention it somewhere explicitly in the docs ?

[fgheysels]

I'd like to come back to this discussion, because I see that not only SwaggerUI is opt out in the template, but the complete availability of the open API spec is opt-out.
You need the Open API spec if you want to import your API in f.i. Azure API Management, so I think it is not a good idea to make the Open API spec generation opt-out as well. The SwaggerUI: that might be opinionated, but having an Open API spec available is a must, don't you think ?

[stijnmoreels]

I was thinking, is this an authenticated call? Otherwise one can authorize admins on such an endpoint. We probably could not do this by default in the template though bc we can't know the authorization roles.

[fgheysels]

No, it's not an authenticated call afaik

[stijnmoreels]

Not sure what to do here 😄 . Maybe we can take this offline, sometime.