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

Response type for "/doc/openapi.yaml" #175

Open pvdbosch opened 6 months ago

pvdbosch commented 6 months ago

When documenting the "GET /doc/openapi.yaml" operation in OpenAPI, as in [doc-refdata], max compatibility with tooling is achieved when specifying the payload as binary:

    OpenApiResponse:
      description: OpenAPI document describing this API
      content:
        application/yaml:
          schema:
            type: string
            format: binary

Non-binary payload type: object has undefined behavior for YAML content-type. Binary format is also the only one allowed currently by the validator.

Can we document this payload format in the guide and add it to openapi-common? I often see problems with it in OpenAPIs (wrong media type or other schema).

Also, we could modify the [doc-refdata] rule to prefer publishing as YAML (SHOULD) over JSON (OPTIONAL), conform to [oas-yaml].

jpraet commented 6 months ago

Is "/doc/openapi.yaml" supposed to be defined in the OpenAPI definition? See https://github.com/belgif/rest-guide/issues/127

How do you handle serving referenced files like /doc/belgif/common/v1/common-v1.yaml? Or do you provide a fat yaml?

pvdbosch commented 6 months ago

Good question. We're currently doing this, as fat yaml, because otherwise the API Gateway blocks the request.

For documentation purpose, its self-referential so leads to chicken-or-egg problem. Maybe useful when client developers have another, possibly different, version of the OpenAPI document and want to check the current version on the server. However, in case of secured APIs, they're probably missing an access token to retrieve it...