Miscellaneous fixes for JSON:API

The current patch looks like an improvement, but it appears the patch drops schema for the relationship routes. For example, the /taxonomy_term/bundle/{entity}/parent and /taxonomy_term/bundle/{entity}/relationships/parent routes have been removed are not being generated by the expectations doc. As a result, this patch still needs some work, before we can merge it.

It looks like this is the result of the below change.

-      if (!$route->getDefault(JsonApiRoutes::JSON_API_ROUTE_FLAG_KEY) || $route->getPath() == $jsonapi_base_path) {
+      $is_jsonapi = $route->getDefault(JsonApiRoutes::JSON_API_ROUTE_FLAG_KEY);
+      $is_entry_point = $route->getPath() === $jsonapi_base_path;
+      $is_related = preg_match('/(\.related)$/', $route_name);
+      $is_relationship = preg_match('/(\.relationship\.)((delete)|(get)|(patch)|(post))$/', $route_name);
+      if (!$is_jsonapi || $is_entry_point || $is_related || $is_relationship) {
         continue;
       }

Previous to this patch, the logic only skipped non jsonapi routes, it now skips all routes which aren't root entity level routes. Is there a reason why these routes were removed here? Is there additional logic which is required to build these routes to have them added back into the doc? I am less familiar with how this is supposed to work, and it would be faster if someone else took a stab at fixing it. To generate expectations locally, set const GENERATE_EXPECTATION_FILES = true; in RequestTest . Then run the test library. I'm happy to worry about doing this if the test failures can be reduced to eliminating following formatted lines or to have a new generic route added.

- /taxonomy_term/taxonomy_term_test/{entity}/relationships/parent' => Array (...)

Forgot to include patch with updated expectations.

Even if the above patch passes, this still not finished pending resolution of the issue noted in #10.

I think you have a valid point, however that's not OpenAPI's objective. The spec is designed and intended to be able to generate a fully working api client, so knowledge of the sup routes is critical. To put it simply, OpenAPI docs doesm't care about the Json:API spec or documentation what so ever and can't assume the user does either.

So yes, your points are valid for the purposes of ReDoc and Swagger, but are against the objectives of OpenAPI spec.

That still doesn't mean we can't build a ui and mechanisms to filter the redoc/swagger uis to limit the data which is returned and displayed in the UIs, and this is what I would suggest as the correct way to implement this as opposed simply removing them. There isn't a spec that I am aware of to implement this, but we currently already have a format for filtering the results by entity type and bundle.

There are already a few open issues for addressing the concerns which you bring up about extra/redundant data cluttering the UIs

• #2874891: Allow filtering doc pages per resource
• #2988260: Allow filtering of OpenAPI docs using the resource id

I think the next step here is to update the patch with one that add the features that were previously missing, and doesn't remove anything.

I don't think Contenta should probably not be patching OpenAPI to alter its functionality, since if this is highly error prone when OpenAPI makes a new release. I think the best path forward is to implement a system of filters, which can be defined by a given generator, and then exposed on the ReDoc and swagger pages, so the user can filter the results to what's relevant. Content can then use a hook alter or another mechanism to default the filters to the limited view.

OpenAPI already supports the passing of the options url parameter to the generator. Currently the available options are only used to control the entity types which are included in the generated doc. This parameter could be used to implement the same functionality for route types and methods as well. Maybe also filtering by tag could be helpful.

Right now there is no api to determine the available filters, so this would be necessary in order to move forward with building a ui to set the filters in ReDoc and Swagger. I may have time to work on this later this week, but no promises. My only thought this far is to have a "getAvailableOption" function on OpenApiGeneratorBase which then can be extended by JsonApiGenerator , to define the relevant filters. I hadn't thought much what kind of data would be returned here. Possibly Data Definitions or JsonSchema. I'm open to recommendations.

My main question for you is to determine what the desired options/filters would be for the jsonapi routes, so that we can start moving this forward.

Thoughts?

I'm can try and focus on the implementation, if you can give me an idea of what you would be expecting to be able to do with it?

With the current api, the $options variable is already exposed, so you can implement the filter code as is. There just isn't a pretty way to display the filter fields in the redoc/swagger ui at the moment. Though, once the filter logic is added, which could be done in your patch, then there is no reason contenta couldn't then alter the redoc page to specify the options that you are looking for

Sadly I don't have available cycles to implement this 😔

I know that feeling all too well. No pressure there. Since you understand what's going on with the current patch better then I, if are able to find the time to get this patch to a point where it no longer removes information, I can will commit it and work on adding the described filtering functionality later this week.

This patch is massive and looks like it reverts a large number of changes to the current HEAD. This includes changes to link names, routes, and other side effects which I don't believe were intentional or relevant to the module. Can you please verify that the patch applies to the lastest head with only the intended changes?

The patch looks good. I've committed it to dev.