Some tooling and generators struggle with the current OpenData which is defined as a security scheme. This is because type: http + scheme: none is not a valid security definition.
To keep documenting intent and optionality without violating OpenAPI, I propose a tag-based approach:
/:
get:
security:
- OpenData: []
tags:
- discovery
- open-data
operationId: landingPage
summary: Landing page
description: >-
Gives a (technical & human readable) output describing how this API must
be used. If the parameter f=html is supplied, a human readable page
must be responded.
externalDocs:
url: https://app.swaggerhub.com/apis/OGC/ogcapi-features-1-example-1/1.0.1
parameters:
- $ref: "#/components/parameters/f"
- $ref: "#/components/parameters/acceptLanguage"
responses:
"200":
$ref: "#/components/responses/landingPageResponse"
default:
$ref: "#/components/responses/errorResponse"And then we define open-data with the necessary description:
tags:
- name: open-data
description: >
Endpoints tagged as open-data may be made publicly accessible
depending on the implementing party. Endpoints with no defined security scheme SHOULD be made publicly accessible, while endpoints
tagged as open-data that have defined security schemes CAN be made publicly accessible if the implementing party wishes.
Some tooling and generators struggle with the current
OpenDatawhich is defined as a security scheme. This is becausetype: http+scheme: noneis not a valid security definition.To keep documenting intent and optionality without violating OpenAPI, I propose a tag-based approach:
And then we define
open-datawith the necessary description: