Is it possible to provide descriptions to hilla-openapi.json file?

Hilla
1

Hello.
We are providing our application with Hilla React UI, but some customers could want to create their own UI. In that case we have to provide Swagger UI for all Hilla endpoints.

In fact, that Hilla generates hilla-openapi.json while building an application. If put this file to /resources/static/v3/api-docs then Swagger UI shows all the endpoints successfully. The only thing I need is to provide descriptions for methods and parameters.

Is it possible?

2

Hi Roman,
As I understand it, the communication between the Hilla React frontend and the Hilla Spring Boot backend is not designed for other consumers to use the backend’s API. Hilla implements the backend-for-frontend pattern. In addition, the communication between frontend and backend contains some Vaadin-specific components, e.g. with regard to security. Therefore, I do not believe that another non-Vaadin consumer would be able to communicate correctly with the backend.

3

I had to disable CSRF protection for that purpose, and successfully tested all the endpoints via Swagger UI based on hilla-openapi.json. It works.

4

I can well imagine that you can use the end points somehow, but I still don’t think that’s a good idea. The communication between the Hilla frontend and backend is Vaadin-specific. You could even go so far as to say that it’s a proprietary RPC-based HTTP API.

If your application wants to offer endpoints that are also intended for other consumers, I would suggest the following design: The generic endpoints are implemented as standalone applications with well-defined HTTP APIs that take certain REST standards into account. The Hilla backend uses these generic APIs and wraps them using a BrowserCallable service, making them available to the Hilla frontend (as described in this blog post, for example). Other applications that want to use the generic endpoints access the standalone applications directly. This way you achieve 2 things: 1. you have a certain degree of reuse for the generic endpoints and 2. you do not rely on the proprietary communication between Hilla backend and frontend, which could theoretically change with every release.

1 Like
5

Thanks for the idea.

6

Just to emphasize what René already described: we might make changes in the way requests and responses are processed in some future version without treating that as a breaking change. For that reason, I recommend against building anything that makes assumptions on the contents of Hilla’s OpenAPI definitions.

2 Likes