search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

Should /doc and /doc/openapi.yaml be defined in the openapi.yaml contract? #127

Closed jpraet closed 1 year ago

jpraet commented 1 year ago

I notice this is done in the https://github.com/belgif/rest-guide-example and wonder if it's a general recommendation to do this?

https://github.com/belgif/rest-guide-example/blob/1fcab76ddc385e01ab85dae96d5909f2b08f04a0/src/main/openapi/openapi.yaml#L385-L413

pvdbosch commented 1 year ago

Providing a /doc resource with a list of links isn't a general recommendation of the rest guide. It might be removed in a future version of the example API.

Offering the /doc/openapi.yaml resource is recommended in https://www.belgif.be/specification/rest/api-guide/#rule-doc-refdata. The guide doesn't say anything about listing it in openapi.yaml but an API Gateway may require it in order not to accept the request. We've encountered some technical challenges with offering the documentation resources however, see: https://github.com/belgif/rest-guide/issues/96#issuecomment-1294994852 ; if they prove to difficult, they may warrant a deviation from the rule.

pvdbosch commented 1 year ago

GET /doc is removed in https://github.com/belgif/rest-guide-example/commit/33e9907c16a1b6ac81f7003c712a4486c950192c