Add endpoint to serve openapi definition

[cthiebault]

I would like to serve my openapi.yaml definition on /api-docs endpoint so I can use it in Swagger UI.

Using Express, I would do: app.use('/api-docs', Express.static('openapi.yaml'));

Maybe we could use a new configuration property to support this new endpoint? Something like:

new OpenAPIBackend({
    definition: 'openapi.yaml',
    serveDefinition: '/api-docs',
    handlers: ...
  });

What do you think?

BTW, thanks for your great job :+1:

[anttiviljami]

Hi @cthiebault ! Thanks for this suggestion.

It's a good idea, and I've wondered about this too before. However, I'm just not sure how to implement this.

See the problem is that the handlers you register are dependent on your platform / framework.

For express the definition handler would look something like this:

function serveDefinition(c, req, res) {
  const definition = c.api.document;
  return res.status(200).json(definition);
}

For hapi:

function serveDefinition(c, req, h) {
  const definition = c.api.document;
  return definition;
}

For aws-lambda:

function serveDefinition(c, event) {
  const definition = c.api.document;
  return {
    statusCode: 200,
    body: JSON.stringify(definition),
    headers: {
      'content-type': 'application/json',
    },
  };
}

See the issue?

I definitely see the convenience of having a default way to serve the input definition through the api.handleRequest method somehow but I'm just not sure how the API should look without making it too difficult.

Feedback would be appreciated!