Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for versioned api #1461

Open
MatGor7 opened this issue Jan 9, 2019 · 10 comments · May be fixed by #2407
Open

Documentation for versioned api #1461

MatGor7 opened this issue Jan 9, 2019 · 10 comments · May be fixed by #2407

Comments

@MatGor7
Copy link

MatGor7 commented Jan 9, 2019

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
Copy link
Collaborator

goetas commented Jan 9, 2019

You can use areas (for the endpoints)

@goetas
Copy link
Collaborator

goetas commented Jan 9, 2019

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

@MatGor7
Copy link
Author

MatGor7 commented Jan 9, 2019

@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
Copy link
Collaborator

goetas commented Jan 9, 2019

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

@GuilhemN
Copy link
Collaborator

GuilhemN commented Jan 9, 2019

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
Copy link
Collaborator

goetas commented Jan 10, 2019

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
Copy link
Collaborator

Sure, we could add that as well.

@mu4ddi3
Copy link

mu4ddi3 commented Feb 11, 2020

Anything new happened here?

@GuilhemN
Copy link
Collaborator

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

@randomsymbols
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants