How to use "$ref" reference and declare components from Swagger in API platform?

2
votes

We can define components in Swagger:

components:
  schemas:
    User:
      properties:
        id:
          type: integer
        name:
          type: string

And use this component later:

responses:
  '200':
    description: The response
    schema: 
      $ref: '#/components/schemas/User'

I want to use this in order to avoid duplicating content.

I try to use this syntax in API Platform:

components:
    schemas:
        Part:
            description: Array of Part
            type: array
            items:
                type: object
                properties:
                    name:
                        type: string

App\Entity\Item:
    collectionOperations:
        post:
            method: 'POST'
            swagger_context:
                parameters:
                    - name: body
                      description: Item data
                      in: body
                      schema:
                          type: object
                          properties:
                              name:
                                  description: Part
                                  type: string
                                  required: true
                              part:
                                  $ref: '#/components/schemas/Part'

It gives me an error:

Exception thrown when handling an exception (Symfony\Component\Config\Exception\FileLoaderLoadException: Resource "components" not found in . (which is being imported from "/app/config/routes/api_platform.yaml"). Make sure there is a loader supporting the "api_platform" type.)

It looks like the YAML loader doesn't recognize the components item.

How can I define and use references in API Platform? How can I define a reference and use it in several YAML files?

2
symfonyapi-platform.com

2 Answers

1
votes

You cannot do that like this.

The components key belongs to the Swagger/OpenAPI format, not to the API Platform configuration (mapping) format. Both API Platform configuration files and Swagger definitions can be written in YAML, but they are not related.

So, as the error message describes, Swagger components cannot be injected in API Platform's configuration files directly, as you try to do.

API Platform's configuration does allow allows to inject some context in the generated Swagger file using the swagger_context key, but you cannot write random Swagger definitions (such as your component key) outside of this structure.

To do what you want to achieve the swagger_context key will not be enough (components must be injected at the root of the Swagger file, and it's not possible with swagger_context).

Instead of using this key, you'll have to create a decorator for the Swagger documentation generator, as explained in this documentation entry: https://api-platform.com/docs/core/swagger/#overriding-the-swagger-documentation

Decorator allows to access to the whole Swagger structure, and to modify it. So you'll be able to add your components structure.

0
votes

It possible ... See How can I annotate my attribute which is Value Object in order that API Platform would generate its fields for swagger documentation?

In my exemple, I have the entity Checker, I created two groups :

 * @ApiResource(
 *     attributes={
 *          "normalization_context"={"groups"={"read"}},
 *          "denormalization_context"={"groups"={"write"}},
 *     },

Then in the swagger_context responses :

 *                  "responses" = {
 *                      "201" = {
 *                          "description" = "....",
 *                          "schema" =  {
 *                              "type" = "object",
 *                              "properties" = {
 *                                   "myresult" = {
 *                                      "$ref"="#/definitions/Checker-read"
 *                                   }