OpenAPI schema is not in line with REST API

[timbms]

1. openAPI schema for WidgetDTO is missing the recursive use of widgets
2. Header Object has neither defined property schema nor content for /rules.
3. X-Atmosphere-Framework is not available as header parameter for operationId = "pollDataForPage" and operationId = "pollDataForPage", though it is used in getPageData.

Expected Behavior

1. A widget can contain widgets (for instance when using Frame in sitemap). Therefore widgetDTO schema needs this addition:

,
"widgets": {
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/WidgetDTO"
  }
}

2. Should set schema or content. I got over my blocking issues with the below manual correction to the json file. Also, in the same context I fixed a bug report by Apimatic "Simple style cannot be used with the current header type." Please note, I am not using the response and could therefore not check the validity for the response. The correction just got me over the build error.

"responses": {
          "201": {
            "description": "Created",
            "headers": {
              "Location": {
                "description": "Newly created Rule",
                "schema": {
              	  "type": "string"
            	}
              }
            }
          },

Apimatic VSCode plugin gives this explanation:

The Header Object must define the type schema for the header using either the schema or content property. The former is used more commonly while the latter is recommended for more complex scenarios involving media types. However, at one time, only one of these properties must be present and not both.

The simple style can only be used when the type of the header is set as array i.e. it cannot be used for primitive or object types.

3. Currently requires a manual correction of the openAPI schema.

Current Behavior

1. Response from server does not match openAPI schema
2. swift-openapi-generator is blocked by this error
3. OpenAPI spec is incomplete

Steps to Reproduce (for Bugs)

use api-explorer

Context

Not able to generate api code with swift-openapi-generator

Your Environment

• Version used: 4.2.0

[timbms]

@wborn I would like to contribute a bug fix. Could you please help me on this issue: What is the command to generate the openAPI json file? Where is it stored in the file system?

[wborn]

AFAIK it's not stored in a file. It's generated using reflection based on the annotations the first time a request is made.

[digitaldan]

To add to what @wborn said, you can see those annotations for example here:

https://github.com/openhab/openhab-core/blob/48e20d660a398b1831c59455ba653fa087c8ab8d/bundles/org.openhab.core.io.rest.sitemap/src/main/java/org/openhab/core/io/rest/sitemap/internal/SitemapResource.java#L264-L270

If you poke around the other REST resources you can get a better idea on how annotations are reflected in the openAPI schema.