when mounting the entire pyramid application at a subpath it's difficult to coordinate that with the api explorer

[mmerickel]

The api explorer is great but it is not dealing with server urls well.

Let's say I have a document like

openapi: '3.0.3'
info:
servers:
  - url: /api
paths:
  /init-app:
    get:
      description: >
        Get some initial data for bootstrapping the static site.
      responses:
        '200':
          description: >
            Initial data for the static site.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitApp'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'

This document is effectively indicating that /api/init-app is an endpoint. Now if I mount my Pyramid application at /prefix (wsgi script_name) then I expect the api explorer and yaml file to be updated to reflect this situation.... for example the server url would be /prefix/api and the endpoint is /prefix/api/init-app.

Fixing this issue would make the document and explorer usable - right now I have to hardcode into my openapi.yaml document that the server url is actually url: /prefix/api.

[zupo]

Fixing this issue would make the document and explorer usable - right now I have to hardcode into my openapi.yaml document that the server url is actually url: /prefix/api.

I think this is the correct approach? Looking from the API consumer/user perspective, I don't care what the backend configuration is, I expect the API to be at the exact URL given in the openapi.yaml file.

Or am I misunderstanding what you are trying to say?

[mmerickel]

Well other than these issues I've opened, my entire codebase is agnostic to the location in which it's deployed and as I stated here the api explorer/yaml are unusable by apps in its current form and in #104 it's unable to validate the api endpoints relative to the app.

[zupo]

Does anything on https://swagger.io/docs/specification/api-host-and-base-path/ help? I'm eager to support your use case as long as we play by the OpenAPI specification rules.

[zupo]

Hey @mmerickel, do you have any further thoughts on this?

[mmerickel]

My thought is I’m annoyed that I can’t define the file relative to the request’s SCRIPT_NAME like every other route. However to fix it would require passing the file and rendering out a new version of the relative server url. If there isn’t an appetite for that then I can understand. I can do it myself - it’s just one of those things in a weird spot between what wsgi likes and what the spec is for. I’d like to think of my openapi.yaml file as a template that the server adapts to the env and y'all (the library) wants to just treat it as static content.

I think it might not be solvable in a way that you would be comfortable with as the maintainer. Something like parsing the file as a template and rendering a copy before serving it to both the explorer and the raw yaml response.

[zupo]

I see. As long as I am the sole maintainer, I'd like to keep it as is, as static content, because I'm afraid I don't have the bandwidth to support the template approach.

That said, hopefully someday in the future we have more people actively maintaining this lib and we can expand to cover the template approach.