Switch to Swagger for api documentation

[caspermeijn]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	How to start?
Documentation	no
Translation	no
CHANGELOG.md	Do I just start a new section?
License	MIT

I work on Read It Later wallabag client and I want better api documentation. I think the first step is updating nelmio/api-doc. This will bring an extended way to document the api.

This PR updates to nelmio/api-doc 3.0 and translates the existing documentation to the new format. I tried to keep the same content as the old api doc.

I have two outstanding issues:

• The {_format) path parameters are not automatically shown in version 3.0. I don't see how this was added in the old version. Which api calls do have the format parameter? I assume this is only a subset of the calls, so want to add these manually.
• nelmio/api-doc 4.0 is not possible, because is will result in a conflict. Do you see a simple way to resolve that conflict?

Makes progress on #2721

[j0k3r]

Good job!

To run test: make test
Also, run CS-Fixer too: php bin/php-cs-fixer fix

[caspermeijn]

I fixed the tests and ran the formatter. I added the _format parameter to the export call, however in this version of nelmio/api-doc the {_format} is always stripped of the path. Please see if this is acceptable.

[j0k3r]

however in this version of nelmio/api-doc the {_format} is always stripped of the path

You mean, on the generated doc?

[caspermeijn]

however in this version of nelmio/api-doc the {_format} is always stripped of the path

You mean, on the generated doc?

Yes, in the generated doc the {_format} is always stripped for the path. That is hard coded in the nelmio code.

[j0k3r]

I've pushed some doc update and added authorization stuff.

Here are some screenshot, before:

After:

[j0k3r]

• nelmio/api-doc 4.0 is not possible, because is will result in a conflict. Do you see a simple way to resolve that conflict?

What was that conflict?

[Kdecherf]

LGTM

[caspermeijn]

• nelmio/api-doc 4.0 is not possible, because is will result in a conflict. Do you see a simple way to resolve that conflict?

What was that conflict?

composer update generates a lot of output. But I think this is main problem:

- nelmio/api-doc-bundle[v4.0.0-BETA1, ..., v4.0.1] require symfony/property-info ^4.0|^5.0 -> satisfiable by symfony/property-info[v4.0.0-BETA1, ..., 4.4.x-dev, v5.0.0-BETA1, ..., 5.4.x-dev].

[j0k3r]

We plan to upgrade to Symfony 4 later, so we'll update the bundle at that time.
Can you squash your commits? And we'll merge it. Thanks for the work!

[caspermeijn]

Can you squash your commits? And we'll merge it. Thanks for the work!

Done