Endpoint /api missing from OpenAPI specification

[philvarner]

It as a requirement to implement the /api endpoint according to the table in the Abstract section of https://rawcdn.githack.com/opengeospatial/WFS_FES/3.0.0-draft.1/docs/17-069.html and 7.3. API definition. However, this is endpoint is not present in the openapi.yaml documentation. I see that it was removed as a result of #7 , however, as an implementer, I find this confusing. Just adding a definition of the endpoint and that it returns an entity of type application/vnd.oai.openapi would make this clear.

[cportele]

I see the point from the view of a server implementation, but I disagree from the viewpoint of a client implementation. For a client that has the API definition the /api path is irrelevant, there is no reason to access that path again as part of using the API. The path of the API definition is "noise".

In addition, looking at other OpenAPI definitions, I am not aware of any example that includes a resource for the OpenAPI definition. To me that is a clear hint that developers do not expect such an entry in the OpenAPI definition.

Maybe it would help, if we no longer require that the OpenAPI definition is always at /api and under the base path, but just require that there is a link from the landing page (with rel=service)? Then the API definition could also be, for example, on SwaggerHub.

[philvarner]

Maybe it would help, if we no longer require that the OpenAPI definition is always at /api and under the base path, but just require that there is a link from the landing page (with rel=service)? Then the API definition could also be, for example, on SwaggerHub.

Yes, I like that proposal. I might name the rel with a more explicit name than service, along the lines of openapi_spec

[cportele]

We will discuss this in the WFS meeting at the OGC TC meeting in Leuven on Monday.

We use registered link relation types whenever we can, this is why we use service. Maybe we could use service-desc for JSON links and service-doc for HTML links (these did not exist yet when we started the work).

[philvarner]

I think that is a good idea.

[pvretano]

@cportele I support the idea of not requiring /api but simply having a link(s) from the landing page. That also allows servers that support legacy versions of WFS to link out to the capabilities document. Cool!

[cportele]

Consensus to remove the requirement to have the API definition at /api. Continue to use /api in an example. Use service-desc and service-doc, too.