0

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?

Aerendir
  • 6,152
  • 9
  • 55
  • 108

1 Answers1

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
Kamil Serafin
  • 11
  • 1
  • I understand the part about the absence of a native mechanism in ApiPlatform to define areas. I don't understand, instead, the problem you are speaking about: I'm currently using both ApiPlatform Swagger UI and also NelmioApiDoc (side-by-side, to test them), but in Nelmio I don't see any duplication (check this: https://github.com/nelmio/NelmioApiDocBundle/issues/2035). It has to be said that I actually can't get areas to work in Nelmio, but I'm trying to understand the problem... Anyway, thank you for your reply! – Aerendir Sep 26 '22 at 09:50