Expose endpoint scopes as part of the generated spec

[paulsturgess]

The openapi spec mentions that we can declare OAuth 2 and OpenID Connect scopes. Apia also has the concept of scopes. I'm not sure that these concepts overlap, we should investigate.

https://swagger.io/docs/specification/authentication/

We should see if it makes sense for us to put these into the schema.

[paulsturgess]

For each endpoint we can declare scopes like this:

/data_centers/:data_center:
    get:
      operationId: get:data_center
      security:
        - Authorization:
          - read
        - OAuth2:
          - core:read
          - core:data
        - ClientCredentials:
          - core:read
          - core:data

We can extract these scopes from Apia because endpoints declare them like this:

class InfoEndpoint < Apia::Endpoint
  scopes 'disks', 'disks:read'
end

However, adding them to the spec makes no difference in the swagger-editor. And also no difference in the generated client code.

We can also declare OAuth2 as a security schema:

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: https://identity.localhost/oauth2/auth
        tokenUrl: https://identity.localhost/oauth2/token
        refreshUrl: https://identity.localhost/oauth2/token
        scopes:
          read: Grants read access
          write: Grants write access
          admin: Grants access to admin operations
          offline_access: Offline

This does allow us to authenticate through the swagger-ui. But requires us to enable CORS in both Hypdra and in Caddy.

• Caddy tweak
• Hydra docs

But we don't currently support oauth2 tokens in the Katapult API. So it's not really worth adding this to our openapi spec until we do.

Our current thinking is that we'd add authorizationUrl, tokenUrl and refreshUrl as options to the middleware when mounting the Apia::OpenApi::Rack middleware in the katapult app.

There is a decision to be made about how the oauth2 scopes will be declared, as they have a prefix/namespace that is different from the existing scopes used by the static access tokens that Katapult currently supports. This is another reason to hold-off.

We should also add "Client Credentials" to the security schemes.

Additional reading:
https://swagger.io/docs/specification/authentication/oauth2/

[paulsturgess]

Blocked by: https://github.com/krystal/katapult/issues/2003

[paulsturgess]

@andrewjtait feel free to add anything else you reckon would be useful for when we come back to this.

[paulsturgess]

Unassigned myself and Andrew because this is non-urgent and won't be worked on soon anyway.