Bentoml: Allow specifying the schema of the endpoints for the Swagger documentation

[omrihar]

When serving the model locally, a nice swagger documentation page becomes accessible that allows you to send requests to the model by clicking the "Try it out" button.
As part of the swagger specification it is possible to specify the schema the endpoint expects. When doing that, the "Try it out" button will be prefilled with values, so that the API end users can experiment with the endpoint more easily.

One library that I know that does this is called FastAPI There they use the type hints provided by the endpoint to infer this (using the excellent pydantic library). While this could be one approach, simply specifying an example to the @api context manager would be more than sufficient.

Thanks,
Omri

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Korusuke]

Hey!
I would like to work on this if no one else is already working on it.

Here are some preliminary thoughts:

• Currently, when you start the BentoML API model server, in the Web UI under Infra tag there are 4 options but the schema for feedback is not defined hence the "Try it out" button doesn't work perfectly. Is this intentional or a feature in progress?

• Also for healthz endpoint, since the response type is set to application/json, swagger doesn't parse the response properly since it is just '\n' and we can change that to text/plain.

• Now for showing the example in swagger UI, we can just have an extra parameter in Handler for example: DataframeHandler(example=example_object)
  For IrisClassifier the example_object would be [[1,2,3,4],[2,3,4,5]].

For testing, I tried this on feedback endpoint:

So is it fine if it's implemented in the way described above or is it to be done in some other way?

[parano]

Hi @Korusuke, thanks for proposing the solution:

Currently, when you start the BentoML API model server, in the Web UI under Infra tag there are 4 options but the schema for feedback is not defined hence the "Try it out" button doesn't work perfectly. Is this intentional or a feature in progress?

Also for healthz endpoint, since the response type is set to application/json, swagger doesn't parse the response properly since it is just '\n' and we can change that to text/plain.

It would be nice to add a response type to the "feedback" and "healthy" endpoint's swagger definition. I believe it was just not yet implemented.

Now for showing the example in swagger UI, we can just have an extra parameter in Handler for example: DataframeHandler(example=example_object) For IrisClassifier the example_object would be [[1,2,3,4],[2,3,4,5]].

That's a great idea! With the latest release and new Input/Output adapters API, the best place to add this parameter would be BaseInputAdapter

[parano]

Thanks @Korusuke for the contribution, this will be available in the next release 0.8.2, scheduled for next Monday.