Support OpenAPI Callbacks

[MatanYadaev]

Prerequisites

• [X] I have written a descriptive issue title
• [X] I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

OpenAPI 3 has a concept of callbacks, which means, async responses for an endpoint.

Currently, Fastify Swagger doesn't support this feature.

Motivation

It's part of the OpenAPI 3 specification. Many APIs use this feature.

Example

Defining the route and the schema:

app.post(
    '/start-process/:id',
    {
        schema: {
            summary: 'Start a process',
            operationId: 'startProcess',
            params: {...},
            body: {...},
            response: {...},
            // Callbacks configuration:
            callbacks: {
                onStart: {
                    '{$request.body#/callbackUrl}': {
                        post: {
                            summary: 'Callback when process starts',
                            operationId: 'onStart',
                            requestBody: {
                                type: 'object',
                                properties: {
                                    id: {
                                        type: 'string',
                                    },
                                },
                            },
                            response: {
                                200: {
                                    description: 'Your server received the callback',
                                },
                            },
                        },
                    },
                },
            },
        },
    },
    () => {
        // Endpoint logic
    },
);

Should generate this OpenAPI spec:

openapi: 3.0.3
info:
  title: Fastify Project
  description: Fastify Project
  version: 0.0.0
components:
  schemas: {}
paths:
  "/start-process/{id}":
    post:
      operationId: startProcess
      summary: Start a process
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
      // Callbacks:
      callbacks:
        onStart:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        status:
                          id: string
              responses:
                "200":
                  description: Your server received the callback

[mcollina]

Thanks for reporting! Would you like to send a Pull Request to address this issue? Remember to add unit tests.

[MatanYadaev]

Hi @mcollina, I tried implementing it and found it a bit challenging. I didn't have enough time to learn and research the project. Could you perhaps suggest a workaround to manually insert callbacks inside the generated OpenAPI Spec? Thanks for your time.

[mcollina]

Have you tried using the transform option?

[MatanYadaev]

@mcollina No, but it will work for me. I am still wondering if there is a better workaround, that is not centralized, for example, make the transform per route, and not in the plugin registration. Something like that:

app.route({
  url: '/users',
  method: 'POST',
  schema: {...},
  transform: (schema) => {
    // Transform here
  },
});

[mcollina]

That would be awesome to implement. You should store that function somewhere in:

app.route({
  url: '/users',
  method: 'POST',
  schema: {...},
  config: {
    swaggerTransform: (schema) => {
      // Transform here
    }
  }
});

[MatanYadaev]

@mcollina I just tried the transform method and it seems to not use the callbacks property I added to the route schema.

[mcollina]

I currently have no bandwidth to investigate.