Doc resource SHOULD be non-secured

[wsalembi]

Add a small addition to https://www.belgif.be/specification/rest/api-guide/#doc-resource

The standard resource /doc/swagger.yaml can be defined as a non-secure resource. Make sure the specification only contains publicly available documentation (no sensitive, personal or secret data) and is only exposed to the access channel (INTERNET, EXTRANET, INTERNAL) where the API is hosted. (cfr Application Security decision dd. 09/06/2022)

/doc/swagger.yaml: security: []

/doc/openapi.yaml: security: []

[pvdbosch]

Should this apply to the whole of /doc/* ?

Maybe it's a business decision up to providers to only expose its API documentation to users with a specific role (e.g. hide deprecated versions, targeted information, ...) vs. openness (API economy). Restricting access to EXTRANET or INTERNAL access channel is just one way of limiting access to a group of users IMO.

Mentioning access channel in the guide may however be a bit too specific to Social Security.

[pvdbosch]

we can remain more general in the guide: Access should at least be allowed to /doc/* content to any (potential) user of the API

[pvdbosch]

I'll create a PR for this change

[pvdbosch]

PR #97 ready for review.

Also, some technical challenges with the doc resources were also brought up during WG, but won't be included in the guide because they can be product-specific:

• API Gateway may require to list every /doc/ resources in OpenAPI in order to permit access to the resources. There isn't a way in OpenAPI to specify an operation for all nested subpaths in /doc/ ; a path parameter only matches until a single path segment (until next slash). It can be doable for a single swagger/openapi file under /doc/, but is harder for multi-file OAS files or nested child resources with documentation. Also may not be ideal to let API Gateway host documentation HTML and images.
• /doc/* duplicates some of the purpose of an API portal, though API's doc on the portal isn't discoverable from the API base path itself; and an API Portal might not exist for non-production environments offering different versions of the API
• having an OpenAPI file on a stable URL is useful to import in SwaggerUI or similar; this is not always the case when an API Portal serves it
• it might be an option to let /doc/openapi.yaml redirect to a static web server with documentation