If docs are disabled, do not try to add a link header to the docs

[Taluu]

Q	A
Bug fix?	yes
New feature?	no
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	~
License	MIT
Doc PR	~

Even if the docs are disabled, the AddLinkHeader listener tries to add a Link header to the api_doc route. But the generator fails if the route does not exists, triggers a 500 instead of having an expected result.

Checking for the parameter %api_platform.enable_docs% solves the problem.

[dunglas]

Hydra cannot work if the docs aren't available. It doesn't make sense to disable the docs without disabling Hydra.

[Taluu]

Not if you have your own docs (like something built with slate, postmann, confluence, ...). It's just that the swagger docs are disabled.

[Taluu]

Maybe what could be done would be to add a parameter or something that points to the doc, which defaults to the generation of the api_doc url ?

[Nek-]

Well the documentation is a feature of hydra. If you decide to remove that feature it should be supported everywhere in api-platform. Or it should throw an exception because of incoherent configuration.

[dunglas]

IMO we must never disable the Hydra docs (or throw) when JSON-LD is enabled. The hydra "doc" is mandatory for JSON-LD (because we use Hydra types everywhere in JSON-LD documents) and Hydra compliance.

[dunglas]

It would be cleaner to remove the service if this flag is set.

[Taluu]

Yup, but wouldn't this be in opposition to the fact that hydra needs this header ? It's the same thing as what I proposed, but still...

[Taluu]

@dunglas But is it obligatory to use swagger for that ? Can't we use something else, and thus not depend on an api_doc route ?

[Nek-]

@dunglas if you disable the documentation it looks pretty normal to disable it from everywhere. A notice may be added to the documentation. For example, I have a fully private application and I don't want to expose any documentation of the service.

Of course, if the documentation would be managed with rights you may make a point to us (we actually have developed a similar system so the front can discover some services). But as it's dangerous, adding the possibility to fully delete any feature related to the doc is relevant.

[dunglas]

After a second look, it looks ok to have partial Hydra support, so 👍 on my side, but can you please add a test?

[Taluu]

test added @dunglas (and I fixed the ContainerBuilder parameter I added that wasn't called on registerJsonLdConfiguration)

[dunglas]

Thanks @Taluu

[insekticid]

Found this bug today too. I have Symfony web page and I do not want to expose any info about api platform outside the world via header Link so I disabled docs and bug appeared.

Waiting for new Api Platform Release @dunglas + have a look at my pull in Symfony PropertyInfo\DoctrineExtractor