Incorrect OpenAPI (Swagger) documentation for application/vnd.api+json

[dmitrach]

Hello.

A project used Api Platform 2.x and have been updated to 3.x, but here I faced a problem with OpenAPI documentation - it does not correspond to the real responses.

API Platform version(s) affected: v3.3.15, v3.4.17 There is no problem on v3.2.26 (good - there is some extra duplicates, but their descriptions are correct), v3.1.29 (ideal - the documentation is the same as the previous version).

Description
The project uses two types of responses:

• application/vnd.api+json
• application/json

The app works correctly, but the documentation of the app is wrong. It contains fields that are not used in the app and should not be included in the response. No groups have been assigned to them anywhere. The problem only for application/vnd.api+json. The documentation includes information about all related entities (maybe not only), but they are not used in the responses.

Below are examples of pieces of documentation.

v3.3.15, v3.4.17 - there are absolutely different refs and their descriptions, but the real responses look like the ref in application/json although the request Accept application/vnd.api+json. It works in WebApp, but the documentation is wrong. The documentation contains ~9600 lines and Swagger UI works very slowly. The description of application/vnd.api+json includes unused fields, like password, emails, and other confident information. Just for fun I used v4.* and I've got wrong documentation and over 16000 lines in the documentation.

      responses:
        '200':
          description: 'Item collection'
          content:
            application/vnd.api+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item.jsonapi'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item-partner.item.read'

v3.2.26 - there are different refs and some duplicates, but their description are the same. The documentation contains ~2000 lines.

responses:
        200:
          description: 'Item collection'
          content:
            application/vnd.api+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item.jsonapi-partner.item.read'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item-partner.item.read'

v3.1.29 - the refs are the same. The documentation looks like it was in v2.7. The documentation contains ~1600 lines.

      responses:
        200:
          description: 'Item collection'
          content:
            application/vnd.api+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item-partner.item.read'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item-partner.item.read'

How to reproduce
I have a typical PHP entity code (Symfony) where a part of properties has groups (#[Groups(['employee:read'])]) and others have no groups. Out API resource has normalizationContext: ['groups' => ['employee:read']]. Some properties are related objects, one of them has the group, but others have not.

[soyuka]

My work around that should definitely fix this issue, could you maybe try my branch at https://github.com/api-platform/core/pull/6960?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[dmitrach]

Hello. Unfortunately I couldn't check the branch. Now I've checked v4.1.19 and there is the same issue. openapi file has over 17700 lines and I cannot open the documentation in a browser through Swagger. v3.* has no updates.

[soyuka]

may you try the 4.2 alpha version?

[dmitrach]

I've tried 4.2.0-alpha.1. It reduces the number of lines to ~8700, but I still have the same problems:

• the documentation cannot be open in the browser
• kind of duplicates of schema descriptions, but they are different and application/vnd.api+json is mistaken.

The result is similar to v3.4.17.

[soyuka]

With 4.2 you should get something like:

                description: 'AbsoluteUrlDummy.jsonapi collection.'
                allOf:
                  - { $ref: '#/components/schemas/JsonApiCollectionBaseSchema' }
                  - { type: object, properties: { data: { type: array, items: { type: object, properties: { id: { type: string }, type: { type: string }, attributes: { $ref: '#/components/schemas/AbsoluteUrlDummy' }, relationships: { type: object, properties: { absoluteUrlRelationDummy: { properties: { data: { type: object, properties: { type: { type: string }, id: { type: string, format: iri-reference } } } } } } } }, required: [type, id] } } } }

the documentation cannot be open in the browser

Swagger ui issue probably try https://pb33f.io/doctor/

kind of duplicates of schema descriptions, but they are different and application/vnd.api+json is mistaken.

Please provide more details of what is wrong: api resource, schema, expected schema, subtract of open api operations. I need to know if the issue is inside:

• json schema
• openapi

You can always check a single schema with:

console api:json-schema:generate 'ApiPlatform\Tests\Fixtures\TestBundle\Entity\Issue5793\BagOfTests' --format=jsonapi --type=output

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[soyuka]

4.2 is out please let me know if this is still actual