search

nelmio / NelmioApiDocBundle

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

Documentation for versioned api #1461

Open MatGor7 opened 5 years ago

MatGor7 commented 5 years ago

Hi, I'm thinking what is your solution to document versioned api. For example I have api in version 1.0 and i want to upgrade api to 1.1. In new version I add new field which is returned via api, how can I show it in documentation. I'm not sure how to create documentation depends on api version. Do you have some idea?

goetas commented 5 years ago

You can use areas (for the endpoints)

goetas commented 5 years ago

Regarding fields, if you are using JMS, it supports versioning, but is not reflected yet on the docs

MatGor7 commented 5 years ago

@goetas Thanks for answer, I'm using JMS and versioning annotations work very well. I have problems with showing it in documentation. I thought about areas, but I think I must create new endpoint with specific url in this solution. What about using versioning via HTTP header? Now I use annotations to create documentation. Maybe i should create files in yml format where i can describe documentation manually for versions, but i hoped that there is a solution to do it in more automatic way.

goetas commented 5 years ago

Hmm. I think this feature is not yet available in nelmio. @GuilhemN am i right?

GuilhemN commented 5 years ago

Is this a request to add jms versioning support? If so it's not supported right now indeed. I think adding a setVersion method to the ApiDocGenerator and the JmsModelDescriber called in the controller would do it fine.

goetas commented 5 years ago

I think adding a setVersion method to the ApiDocGenerator and the JmsModelDescriber called in the controller would do it fine.

Sounds a very good idea.

Shouldn't be part of the model as well? should be considered as if it is something similar to groups IMO...

GuilhemN commented 5 years ago

Sure, we could add that as well.

mu4ddi3 commented 4 years ago

Anything new happened here?

GuilhemN commented 4 years ago

@mu4ddi3 No, if you'd like to submit one, a PR would be welcome.

randomsymbols commented 4 years ago

What about documentation.info.version in case we use areas for API versioning? Shouldn't it represent the current API version? It seems it is impossible to have multiple documentation.info.version in nelmio_api_doc.yaml.