Nelmioapidocbundle: [3.0][RFC] Support views (?)

[magnetik]

The ApiDocBundle v2 supported views to generate multiple documentation with different routes in it.

I've an use case that's quite similar to the one expressed in the legacy documentation: I'd like to expose some features to some user (got some "internal" routes) and other to everyone ("public") routes.

Should the support be added in the 3.0 version?

[GuilhemN]

This is not supported by Swagger so I'm not sure how we could support it: a custom field (e.g. x-view), using path filters?

The first one would be convenient, the second one would be harder to implement as the bundle is not meant to generate different docs for a single app.

[yarcowang]

Well, I like tags and views, so I can figure out the API version. And show them by versions.
But I didn't see it in swagger example , don't know how they do that.

[GuilhemN]

@yarcowang this is not obvious at first sight, but each tag is shown on top of a collection of routes. The first one is pet: Everything about your Pets. views is not supported by swagger.

[yarcowang]

So... How do you guys dealing with versioning in the doc?
I think different versions of APIs in one page must be messed up.

[GuilhemN]

What about doing this with tags and hiding the unwanted tags in js?

[yarcowang]

@GuilhemN Sounds good to me...

[dbu]

feel free to send a pull request for this @yarcowang if what is now available in the bundle v3 is not enough

[GuilhemN]

I think areas support (https://symfony.com/doc/current/bundles/NelmioApiDocBundle/areas.html) solve exactly this. It is to be released in 3.1.