Loopback-next: Serve OpenAPI spec from a controller method

[bajtos]

At the moment, we use a hacky workaround in RestServer to implement an HTTP endpoint serving OpenAPI spec describing the application.

https://github.com/strongloop/loopback-next/blob/9591f87dee722be4dcc2a8732894f27a64188cfb/packages/rest/src/rest.server.ts#L194-L208

We need to find a cleaner solution. @raymondfeng is proposing to implement /openapi endpoint as a regular controller method. To do that, we need to enable controller methods to control response headers like content-type, see e.g. #436 and loosely related #788.

@bajtos argues that /openapi endpoint should not be implemented as controller methods:

Regular routes are handled through Sequence. IMO, the built-in OpenAPI endpoint should not run through a Sequence, because it's not part of the application API itself. E.g. if the app implements access/audit logs, I don't want this endpoint to trigger a log entry. If the server implements content-negotiation to support XML clients, I don't want the OpenAPI spec to be converted into an XML response.

[virkt25]

Maybe we need a better way of putting in the hacky URL's. Another issue I see with the spec controller would be what if someone deletes the controller because they don't understand the purpose. I think it should stay an internal endpoint ... but we need a way of defining endpoints not part of the sequence change ... just like static files.

[raymondfeng]

@bajtos argues that /openapi endpoint should not be implemented as controller methods:

Regular routes are handled through Sequence. IMO, the built-in OpenAPI endpoint should not run through a Sequence, because it's not part of the application API itself. E.g. if the app implements access/audit logs, I don't want this endpoint to trigger a log entry. If the server implements content-negotiation to support XML clients, I don't want the OpenAPI spec to be converted into an XML response.

We can argue the other way too. Having such routes out of bound can have security implications as some applications might want to only expose such specs to admin console with ACL.

We also need to consider other endpoints such as /health or /metrics.

Extension modules should be able to contribute such endpoints in addition to applications.

[bajtos]

We can argue the other way too. Having such routes out of bound can have security implications as some applications might want to only expose such specs to admin console with ACL.

Makes sense too.

We also need to consider other endpoints such as /health or /metrics.

Good point.

I think at minimum, we need a flag to say that a controller method should not be described in OpenAPI spec we are generating for the app.

[jannyHou]

Another issue I see with the spec controller would be what if someone deletes the controller because they don't understand the purpose. I think it should stay an internal endpoint ...

How about create the controller class in the @loopback/rest package instead of creating it by cli? This can prevent people from removing it.

If this results in a circular dependency, we can create a new package for some built-in classes, or other artifacts. Just like the built-in models in loopback.

I think at minimum, we need a flag to say that a controller method should not be described in OpenAPI spec we are generating for the app.

+1 👍

[virkt25]

On the one hand I like the idea of certain endpoints always being present such as /openapi.json so am ok with it being part of @loopback/rest ... but at the same time shouldn't users have the option of disabling it? --- Then again, we don't provide an option to users right now so it's probably fine.

[stale[bot]]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[stale[bot]]

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.