Nelmioapidocbundle: [3.0] Should we remove the ApiDoc annotation ?

[GuilhemN]

If we decide to merge https://github.com/nelmio/NelmioApiDocBundle/pull/938, then the Swagger-php annotations will be very powerful and easy to use.
In that case, we can wonder whether @ApiDoc will still be useful.

My biggest concern is about models: Swagger-php can't guess how a model is whereas this bundle can when using @ApiDoc::$input and @ApiDoc::$output; so if we only use Swagger-php we'll loose that part.

[joelwurtz]

IMO it should be kept for BC and propose a upgrade path, even if it's 3.0 it doesn't mean we should be BC here (as it's really a core feature, many people will be blocked for upgrading if we remove this)

[GuilhemN]

I agree but @dbu's arguments are also true :

having redundant annotations to do the same thing is confusing (and could create ambiguities if both are defined and contradicting).

i would use the major version change to get rid of the unneeded
annotations. they are easy to batch replace in user code. having 2 for the
same is really confusing

Imo we should keep its primary fields but disadvise to use it and advise to use instead swagger-php annotations.

[joelwurtz]

agree on that but the removal should be on a 4.0 not 3.0, or we should provide a intermediary version in the 2.x versions (so user can upgrade at their own pace, change and test a single endpoint and then repeat this process)

[GuilhemN]

@joelwurtz having a last 2.x version should be better but it would require a certain investment to support swagger-php. I don't think it is worth it as it is much easier to support @ApiDoc in 3.0.
Maybe we can directly deprecate @ApiDoc in 3.0, it sounds weird but it would clarify our position without complexifying the migration.

[dbu]

i would not go to the hassle of providing a 2.x version with swagger-php support.

i also would not provide redundant annotations, not even for BC.

the things that @ApiDoc can that swagger-php can't should still be supported of course. either by keeping just those parts of @ApiDoc or by adding some new annotations to either swagger-php or here.

[GuilhemN]

@dbu then should we send people to a tool like yours to do their migration at once ?

[dbu]

that could help. forgot that i wrote that :-)

sooner or later the migration has to happen anyways, no point in
postponing that. there will be some migration needed anyways, imho its
better to have that once than carrying technical debt around and needing
to migrate the rest of your annotations again later.

[GuilhemN]

If we provide a tool to do the migration easily, then it's fine for me to remove @ApiDoc.

I agree with you it is better to fix the technical debt asap but it can be hard on a big codebase, having a tool is mandatory imo if we want to remove @ApiDoc in 3.0.

[willdurand]

If we provide a tool to do the migration easily, then it's fine for me to remove @ApiDoc.

:+1:

[magnetik]

I've mixed feelings about this.

Will it be possible to use swagger-php annotations for the needs and evolution of this bundle?
For instance can #940 be done without losing the compatibility with swagger-php?
Also for #938, will the resulting annotation work with swagger-php? If not I would prefer that this bundle define it's own annotation (even if it mimics most of swagger-php one's).
.

[GuilhemN]

Will it be possible to use swagger-php annotations for the needs and evolution of this bundle?

We'll still be able to create our own annotations if we have the need (I only see models for now).

For instance can #940 be done without losing the compatibility with swagger-php?

Do you mean moving an app using swagger-php to NelmioApiDocBundle?
If yes, it is possible, my PRs are extending Swagger-php but it is not modified itself. However the opposite (NelmioApiDocBundle to an app using only Swagger-Php) won't be possible as the bundle proposes features on top of Swagger-Php annotations.

[dbu]

i would not suggest a general policy to not have annoations provided by
this bundle. it might even make sense to keep ApiDoc itself but with
less parameters - i just think we have to avoid duplicate annotations
for the same things.

[manuelbcd]

Let me clarify myself. I'm happy with swg-php annotations but... what happens with doctrine reflection? Is swg-php supporting auto extraction of information from object like ApiDoc do? It's one of the best features of ApiDoc bundle.

[GuilhemN]

@manuelbcd this is what would solve https://github.com/nelmio/NelmioApiDocBundle/pull/943.

[manuelbcd]

+1 again. Thanks @GuilhemN

[GuilhemN]

Done in #945, thanks !