openAPI v3 - Callbacks feature

[CyrilleBenard]

Description

New feature :

I was wondering when the callbacks feature (openAPI v3) will be planned to be developed in the openapi-generator ?
The 2 "languages" I'm interesting in are :
C++ (cpp-pistache-server and cpp-restsdk)
Java (jaxrs-resteasy)

Below a small openapi file useful to check this feature

openapi-generator version

N/A

OpenAPI declaration file content or url

openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple Callback example
  description: Validate a simple callback
paths:
  /subscribe:
    post:
      summary: Subscribe to a notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl: 
                  type: string
                  format: uri
                  example: http://client_domain/the_call_back_endpoint
              required:
                - callbackUrl
      responses:
        '201':
          description: Subscription created
        '403':
          description: Forbidden

      callbacks: 
        onEventReport: 
          '{$request.body#/callbackUrl}': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Event 01 raised
                      required:
                        - message
              responses: # Expected responses (from the client) to the callback message
                '204':
                  description: Successful acknowledgement
                default:
                  description: Unexpected error

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Simple Callback example",
    "description": "Validate a simple callback"
  },
  "paths": {
    "/subscribe": {
      "post": {
        "summary": "Subscribe to a notification",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "callbackUrl": {
                    "type": "string",
                    "format": "uri",
                    "example": "http://client_domain/the_call_back_endpoint"
                  }
                },
                "required": [
                  "callbackUrl"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "callbacks": {
          "onEventReport": {
            "{$request.body#/callbackUrl}": {
              "post": {
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "Event 01 raised"
                          }
                        },
                        "required": [
                          "message"
                        ]
                      }
                    }
                  }
                },
                "responses": {
                  "204": {
                    "description": "Successful acknowledgement"
                  },
                  "default": {
                    "description": "Unexpected error"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Command line used for generation

N/A

Steps to reproduce

N/A

Related issues/PRs

N/A

Suggest a fix/enhancement

N/A

[srividhyak27]

Hi,

Looking for this feature in openapi-generator.
For language jaxrs-jersey.

Currently using openapi-generator-maven-plugin (version 3.1.2)

Getting the below warning and a subsequent error

[WARNING] Exception while reading:
com.fasterxml.jackson.core.JsonParseException: Expected a field name (Scalar value in YAML), got this instead: <org.yaml.snakeyaml.events.MappingStartEvent(anchor=null, tag=null, implicit=true)>
at [Source: (StringReader); line: 46, column: 12]
at com.fasterxml.jackson.core.JsonParser._constructError(JsonParser.java:1804)

[ERROR] failed to read resource listing
com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'openapi': was expecting ('true', 'false' or 'null')
at [Source: (String)"openapi: 3.0.0

Is the error due to the previous warning ?
Is there any way to ignore/pass through the warning and generate code for rest of the openapi 3.0.0 yaml specification ?

Thanks,
Srividhya

[jmini]

Can you maybe open a new issue (can be related to this one) where you post all the requested elements to reproduce the problem?

[srividhyak27]

Created new issue - #800

[glockhart]

@jmini are there any timelines for when this work might be scheduled?

[jmini]

Well the development of OpenAPI-Generator is community driven... Which means that features are developed as quick as PR comes in.

There is no schedule, because nobody knows when he will have enough time to implement a feature.

If you've time to help implement this feature, we can show you some good starting points

[glockhart]

ok, I have one engineer that may be able to start working on this in a few days and could contribute a PR if the effort isn't massive.

If you could send on those starting points then we'll take a look and see if it's something we can deliver in a reasonable amount of time

[devplayer0]

@jmini would you be able to post that information on getting started with this?

[wing328]

Let me try to share more details by this weekend

[wing328]

First of all, thanks for offering help to add the callback support.

A good starting point is the fromOperation method, which converts the operation's values obtained from the spec into Codegen objects (e.g CodegenResponse) for code generation.

The third parameter Operation operation contains the following to store callbacks

    private Map<String, Callback> callbacks = null;

    public Map<String, Callback> getCallbacks() {
        return this.callbacks;
    }

    public void setCallbacks(Map<String, Callback> callbacks) {
        this.callbacks = callbacks;
    }

    public Operation callbacks(Map<String, Callback> callbacks) {
        this.callbacks = callbacks;
        return this;
    }

You will probably need to create CodegenCallback model to store the Callback and fromCallback method similar to what we've done for Response as an example

Please let me know if you need information on callbacks.

Ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8

[jmini]

The OpenAPI-Tool can be summarised into 3 steps:

Step 0/ An OpenAPI specification is parsed with Swagger-Parser and OpenAPI-Generator gets as input a model representing the OpenAPI Spec. => this is an external lib we use.

Step 1/ This model is transformed according to some logic that is command and/or targeted-language specific into a second model built with the Codegen* classes.
(CodegenModel, CodegenProperty, CodegenOperation…).

Step 2/ This second model is used in some mustache templates to generate the code.

---

To support a new construct, the first step is to add the necessary information to the Codegen layer.
In the codegen layer, the information should work for all generators, it should not be language specific (but the value can be).
For example: there is one field CodegenProperty.dataType, its value will be different if a java generator or a typescript generator is used. But we do not have CodegenProperty.javaDataType or CodegenProperty.typescriptDataType.

The codegen layer is not only a copy of the OpenAPI Model it can contain additional computation (ensure uniqueness of a name, convert special chars in names to be compatible with the targeted language, group operation by tag, compute json example…)

Then the second step is to use this information in the templates.

---

Examples:

• support for variables in the server definitions: Added server variable support #816 (Step 1 only)
• support for discriminator: Support for discriminator.mapping #536 (Step 1 and Step 2 for java generators)

---

To start with the implementation of this issue, I would start to add the necessary information in the codegen model.