Incorrect OpenAPI (Swagger) Documentation For Application/vnd.api+json

by ADMIN 71 views

Introduction

When upgrading from API Platform 2.x to 3.x, developers may encounter issues with OpenAPI documentation. In this article, we will discuss a specific problem that arises when using the application/vnd.api+json media type. This issue is particularly relevant to API Platform versions 3.3.15 and 3.4.17, although it may also affect other versions.

Problem Description

The problem lies in the incorrect OpenAPI documentation for the application/vnd.api+json media type. This type of response is used in conjunction with the application/json media type, and the application works correctly. However, the documentation contains fields that are not used in the application and should not be included in the response. These fields are not assigned to any groups and are only present in the application/vnd.api+json documentation.

Examples of Incorrect Documentation

Below are examples of pieces of documentation that demonstrate the issue:

v3.3.15 and v3.4.17

      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'

In this example, the application/vnd.api+json documentation includes a reference to the Item.jsonapi schema, which is not used in the application. The application/json documentation, on the other hand, references the Item-partner.item.read schema, which is used in the application.

v3.2.26

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'

In this example, the application/vnd.api+json documentation includes a reference to the Item.jsonapi-partner.item.read schema, which is not used in the application. The application/json documentation, on the other hand, references the Item-partner.item.read schema, which is used in the application.

v3.1.29

      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'

In this example, the application/vnd.api+json documentation includes a reference to the Item-partner.item.read schema, which is used in the application. The application/json documentation also references the same schema.

How to Reproduce

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

Conclusion

In conclusion, the incorrect OpenAPI documentation for the application/vnd.api+json media type is a known issue in API Platform versions 3.3.15 and 3.4.17. This issue can be reproduced by creating a typical PHP entity code with groups and no groups, and using the normalizationContext option in the API resource. The documentation contains fields that are not used in the application and should not be included in the response. To resolve this issue, you need to investigate the documentation and remove the unused fields.

Possible Solutions

To resolve this issue, you can try the following solutions:

  1. Investigate the documentation: Review the OpenAPI documentation and remove the unused fields.
  2. Use the groups option: Use the groups option in the normalizationContext to specify the groups that should be included in the response.
  3. Use the exclusion_policy option: Use the exclusion_policy option to specify how to handle excluded properties.
  4. Update the API Platform version: Update the API Platform version to a newer version that may have fixed this issue.

Additional Information

  • API Platform version(s) affected: v3.3.15, v3.4.17
  • Description: The project uses two types of responses: application/vnd.api+json and 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 affects application/vnd.api+json.
  • 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. My API resource has normalizationContext: ['groups' => ['employee:read']]. Some properties are related objects, one of them has the group, but others have not.

Introduction

In our previous article, we discussed the issue of incorrect OpenAPI documentation for the application/vnd.api+json media type in API Platform versions 3.3.15 and 3.4.17. This issue can cause problems with the documentation, including the inclusion of unused fields and incorrect references. In this article, we will provide a Q&A section to help you better understand the issue and its possible solutions.

Q: What is the cause of the incorrect OpenAPI documentation?

A: The cause of the incorrect OpenAPI documentation is due to the way API Platform generates the documentation for the application/vnd.api+json media type. In API Platform versions 3.3.15 and 3.4.17, the documentation includes fields that are not used in the application and should not be included in the response.

Q: How can I reproduce this issue?

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

Q: What are the symptoms of this issue?

A: The symptoms of this issue include:

  • The documentation contains fields that are not used in the application and should not be included in the response.
  • The application/vnd.api+json documentation includes incorrect references to schemas.
  • The documentation is slow to load due to the large number of lines.

Q: How can I fix this issue?

A: To fix this issue, you can try the following solutions:

  1. Investigate the documentation: Review the OpenAPI documentation and remove the unused fields.
  2. Use the groups option: Use the groups option in the normalizationContext to specify the groups that should be included in the response.
  3. Use the exclusion_policy option: Use the exclusion_policy option to specify how to handle excluded properties.
  4. Update the API Platform version: Update the API Platform version to a newer version that may have fixed this issue.

Q: What are the possible solutions for this issue?

A: The possible solutions for this issue include:

  1. Remove unused fields: Remove the unused fields from the documentation to prevent them from being included in the response.
  2. Use the groups option: Use the groups option in the normalizationContext to specify the groups that should be included in the response.
  3. Use the exclusion_policy option: Use the exclusion_policy option to specify how to handle excluded properties.
  4. Update the API Platform version: Update the API Platform version to a newer version that may have fixed this issue.

Q: What are the benefits of fixing this issue?

A: The benefits of fixing this issue include:

  • Improved documentation accuracy
  • Reduced documentation size
  • Improved performance
  • Better security

Q: What are the consequences of not fixing this issue?

A: The consequences of not fixing this issue include:

  • Inaccurate documentation
  • Large documentation size
  • Poor performance
  • Security risks

Conclusion

In conclusion, the incorrect OpenAPI documentation for the application/vnd.api+json media type is a known issue in API Platform versions 3.3.15 and 3.4.17. This issue can cause problems with the documentation, including the inclusion of unused fields and incorrect references. By understanding the cause and symptoms of this issue, you can take steps to fix it and improve the accuracy and performance of your API documentation.

Additional Information

  • API Platform version(s) affected: v3.3.15, v3.4.17
  • Description: The project uses two types of responses: application/vnd.api+json and 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 affects application/vnd.api+json.
  • 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. My API resource has normalizationContext: ['groups' => ['employee:read']]. Some properties are related objects, one of them has the group, but others have not.