ApiPlatform API docs: how to create areas like in NelmioApiDocs?

Question

I'd like to create "area"s in docs generated by ApiPlatform.

Something like NelmioApiDocs allow to do (https://symfony.com/bundles/NelmioApiDocBundle/current/areas.html)

Is it possible in ApiPlatform? How

If not, is there any other concept that can be used to make the documentation more readable when there are many endpoints?

Answer 1

As far as I know, there is no mechanism in the API Platform that can handle multiple documentation. Although installing independently NelmioApiDocBundle can be a workaround for you. If configured properly you can create areas that are separate from API Platform autogenerated documentation.

There is only one problem with this solution. If you are using API Platform for configured areas documentation is duplicated. Endpoints that are supposed to be only in doc bundle are also in swagger generated by API Platform. To fix that problem you can decorate API platform swagger normalizer:

final class HideCoreDocsNormalizer implements NormalizerInterface {
  private const DOCS_PATHS = [
    '/api/foo/docs',
    '/api/foo/docs.json',
  ];

  public function __construct(
      private RequestStack $requestStack,
  ) {
  }

  /**
   * @param Documentation $object
   * @param array<string, mixed> $context
   *
   * @return mixed[]|string|int|float|bool|null
   */
  public function normalize($object, $format = null, array $context = []): mixed
  {
      return null;
  }

  public function supportsNormalization($data, $format = null): bool
  {
      if ($this->requestStack->getCurrentRequest() === null) {
          return false;
      }

      return in_array($this->requestStack->getCurrentRequest()->getPathInfo(), self::DOCS_PATHS);
  }
}

And in configuration file:

Foo\Bar\Serializer\HideDocsNormalizer:
decorates: 'api_platform.swagger.normalizer.api_gateway'
arguments: [ '@request_stack' ]
autoconfigure: false