Documentation for versioned api

[MatGor7]

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]

You can use areas (for the endpoints)

[goetas]

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

[MatGor7]

@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]

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

[GuilhemN]

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]

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]

Sure, we could add that as well.

[mu4ddi3]

Anything new happened here?

[GuilhemN]

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

[randomsymbols]

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.