search

nelmio / NelmioApiDocBundle

Generates documentation for your REST API from annotations
MIT License
2.23k stars 835 forks source link

Using JMS\Discriminator for multiple input/output types. #285

Closed h4cc closed 6 years ago

h4cc commented 10 years ago

We are using JMS\Discriminator for our Entities and would like to express that in the apidoc.

Currently, we can just use the Base Entity, that does not contain all the information :(

Would be a very cool feature, if it would be possible to introspect the discriminations and supply multiple input or output types in the documentation.

willdurand commented 10 years ago

Ok. I don't really know what "discrimator" is, so I suggest you to work on this feature :)

h4cc commented 10 years ago

I made a small example with according JSON output: https://gist.github.com/h4cc/8313723

Doctrine MongoDB has also a discriminator feature, that works well in combination with jms. http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/inheritance-mapping.html#single-collection-inheritance

My first idea would be, if its @ApiDoc{output="AbstractUser"}, all the "child" Classes like "User" and "Moderator" would be collected and (somehow) integrated in the "Return" part of the report. Or would there by a better way to display multiple possible return Entites? Till now only one type of Return seems to be assumed.

mtotheikle commented 10 years ago

For output I think if we update the response to look something like the following it would work. http://swagger.wordnik.com/#!/pet/findPetsByStatus_get_1

In case the link does not work look at the findPetsByStatus API method and the response output it documents.

h4cc commented 10 years ago

Ah, ok. The return format of the response in swagger might fit better. But that sounds to me like a different story, that has to be implemented first.

Although the swagger response does not make clear, that it could be multiple different response types like User and Moderator.

mbedna commented 10 years ago

Hello,

Could you please review above pull requests?

h4cc commented 10 years ago

I tested the feature branch and its working for my API. Like the HTML view with the tabs :+1:

mbedna commented 10 years ago

@h4cc Thanks for you comment. Will it be possible then to merge this change or it needs further improvement?

h4cc commented 10 years ago

As far as i can see, all needed functionality is given. The coding looks good and tests are available. :+1:

mbedna commented 10 years ago

Unfortunately there is one issue. Required fields are not shown correctly with this solution.

dbu commented 6 years ago

i am closing old tickets without activity. feel free to open a new issue if needed.