Correct OpenAPI specification for returning HTML from a API call

user_91020 0
Viewed 41

I know this may sound odd, but we have an API where we return back out generated HTML content depending on payloads passed in.

I'm just wondering what is the formal definition of a Open API call for such a api, specifically the responses section below.

Is it as simple as this?

    "paths": {
    "/instance/UI/{instanceCode}/{identifier}": {
        "get": {
            "summary": "Returns the UI which allow the instances answer to be managed by a user",
            "operationId": "instanceUIGet",
            "parameters": [
                {
                    "name": "instanceCode",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "identifier",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "responses": {
                "200": {
                    "description": "Returns the HTML page for a UI to manage the instance.",
                    "content": {
                        "text/html": {
                        }
                    }
                }
            }
        }
    },
swagger openapi
1 Answers

It would be either

"responses": {
    "200": {
        "description": "Returns the HTML page for a UI to manage the instance.",
        "content": {
            "text/html": {}    // no schema needed
        }
    }
}

(as in your example)

or

"responses": {
    "200": {
        "description": "Returns the HTML page for a UI to manage the instance.",
        "content": {
            "text/html": {
                "schema": {
                    "type": "string"
                }
            }
        }
    }
}

Some comments by the OpenAPI Specification maintainers suggest that the text/* media types don't need a schema because their semantics is fully defined by the media type itself. However, if you search for text/ in the specification itself, you'll notice the use of schema in some of the examples with the text/* media types. Looks like there's no official stance on that (or maybe the examples in the spec are not quite correct).

user_1131160
Related