Support for JSON:API - Githubissues

line / armeria

Your go-to microservice framework for any situation, from the creator of Netty et al. You can build any type of microservice leveraging your favorite technologies, including gRPC, Thrift, Kotlin, Retrofit, Reactive Streams, Spring Boot and Dropwizard.

https://armeria.dev

Apache License 2.0

4.83k stars 921 forks source link

Support for JSON:API #2402

Open OneCricketeer opened 4 years ago

OneCricketeer commented 4 years ago

While DocService seems useful, it might get more benefit from having a JSON-API spec.

https://jsonapi.org/

https://jsonapi.org/implementations/#client-libraries-java

trustin commented 4 years ago

Do you suggest that 1) DocService API itself needs a JSON-API spec or 2) DocService needs to generate JSON-API specs for the user services?

OneCricketeer commented 4 years ago

I'm not sure what (1) would provide since it's mostly documentation anyways while allowing you to invoke the services defined in the Server, right?

Therefore, leaning towards (2)

From one link

Crnk is lightweight, modular and almost dependency-free. It is a library that integrates well with basically everything from Spring Boot, Vert.x, JAX-RS, servlets and others

Therefore, I suppose it could be an external module, but outside of gRPC/Thrift, I think you've got some overlap with some features that OpenAPI or JSONAPI provide

trustin commented 4 years ago

Therefore, leaning towards (2)

OK. Sounds reasonable. Some additional questions:

What service types would you expect Armeria to support? I guess not all services can produce JSON-API spec, but some may be possible? e.g. annotated services
- Is is possible to generate practically useful spec from Armeria services? We previously tried that for OpenAPI and the result wasn't that great, because it wouldn't work without adding more annotations manually. We ended up with focusing on spec-to-code generator instead of code-to-spec generator (#2245 by @moonchanyong).
Should this be done as an offline tool or should DocService generate the spec only when the server is running?

OneCricketeer commented 4 years ago

Annotated services seems a good start to me, at least looking at the Crnk implementation.

If an offline client generator is possible like swagger-codegen, that would be nice, however, I feel that's out of scope for just the context of a server able to follow/implement the spec, so "when the server is running"

minwoox commented 4 years ago

We previously tried that for OpenAPI and the result wasn't that great, because it wouldn't work without adding more annotations manually.

Yes, I tried but couldn't finish it. 😅 You might want to check out the code. We needed to add more annotations which are just for describing the service behavior. The problem was that the description is not from the code but just a string, it tends to become diverse from the service as the service grows. So we stopped there implementing and wanted to use different approaches such as using test code as REST Docs does.

If we can prevent that situation, it will be nice to have these features. 🤔