search

jorge07 / symfony-6-es-cqrs-boilerplate

Symfony 6 DDD ES CQRS backend boilerplate.
MIT License
1.07k stars 187 forks source link

Improve API doc content #161

Closed jon-ht closed 3 years ago

jon-ht commented 4 years ago

Current documentation of the API is a bit "poor", it doesn't use all potential of Swagger/OpenAPI spec.

What I suggest is to update Nelmio to its newly released v4 (https://github.com/nelmio/NelmioApiDocBundle/releases/tag/v4.0.0-BETA1).

I already have an almost ready PR for this, but it's based on https://github.com/jorge07/symfony-5-es-cqrs-boilerplate/pull/160 for serialization groups. Depending on your thoughts, I may rebase to remove this dependency and add a serialization based documentation on another PR

jorge07 commented 4 years ago

I really would like to migrate to openApi + have a proper library to control that response are openApi complient

jon-ht commented 4 years ago

So, here is what I've got so far https://imgur.com/s1NThhf. I think there is a good basis for describing API input/output.

That being said, wouldn't it worth to add API Platform as a "middleware" ? It could expose commands/queries via autogenerated API doc and validate inputs. Plus, pagination is already handled in their core, same for serializarion and elasticsearch (didn't had time to test yet)

jorge07 commented 4 years ago

It can be a good replacement for the api controllers. I've never used but I'm open to give a try and learn about it

jon-ht commented 4 years ago

Hi @jorge07 !

Sorry to not came back before, I was working on a draft for API Platform proposal. You can find my demo repo here https://github.com/jon-ht/api-platform-cqrs-es

I've started from scratch with Symfony 5.1, not all files have been reported yet and I'm still missing tests (will work on it soon)

When this project will be mature enough, I propose to open a PR here and close mine if you want (it's your project after all 😉))

Would be nice if you could take a look to give me your feedback. Don't hesitate to tell me if I'm doing something wrong

jorge07 commented 4 years ago

Nice, will do!

jorge07 commented 4 years ago

I left an issue in the repo with my initial feedback.

jorge07 commented 3 years ago

Will be fixed in #194

jorge07 commented 3 years ago

Thanks @jon-ht for all the feedback received here. I just moved to V4, released a week ago, and specs now follow openAPI and have outputs and inputs in doc