Authress-Engineering / openapi-explorer

OpenAPI Web component to generate a UI from the spec.
Apache License 2.0
291 stars 42 forks source link

Rendering property with allOf ignores title and description #257

Open adam-homeboost opened 4 days ago

adam-homeboost commented 4 days ago

I have an object with an allOf listing a $ref. In this case, the title and description fields are ignored and only the schema name is used in those locations.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Some API",
    "summary": "",
    "description": "",
    "version": "alpha"
  },
  "paths": {
    "/api/v1/whatever/": {
      "post": {
        "parameters": [],
        "responses": {
          "200": {
            "description": "A Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NumericValue_str_": {
        "properties": {
          "nv": {
            "type": "string"
          }
        }
      },
      "Response": {
        "properties": {
          "value": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NumericValue_str_"
              }
            ],
            "title": "My Title",
            "description": "My Description"
          }
        }
      }
    }
  }
}

Result:

image

Wanted:

image

(also, I'm not clear on the what is happening with the font size there, but honoring the title and description content is what I am after here).

If the $ref is moved outside an allOf or if its an anyOf instead, then it works as expected. Having more values in the allOf does not help.

wparad commented 4 days ago

Hmm, looking at what you have shown, it looks like the type column might be correct but the description is wrong. The type column is meant to represent the actual named typed that is created from SDK generators, etc.. not a helpful field name. Agreed though in the case of "allOf" it isn't clear what that table cell display string should actually be. For instance if you have an SDK for your API what is the name of the schema?

adam-homeboost commented 3 days ago

Yes, I agree that the type ought to remain as the actual schema name. The description is what is needed more. Cases like this, where there is ambiguity is where its most important to be able to manually control this area. I will admit that I am unclear on just why my schema generator is choosing to use allOf here, especially with only one value, but so far as I can tell, it is a legitimate use case in general. For this specific instance, I think my schema generator could do a better job at what I am asking it to do, but I don't think that problem is as relevant so long as I can get the overriding title and description to work.

wparad commented 3 days ago

Yeah, that part is definitely seems a bug. Thanks for finding this.