Correct OpenAPI specification for returning HTML from a API call

Question

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": {
                        }
                    }
                }
            }
        }
    },

Helen · Accepted Answer · 2022-07-06 19:51:52Z

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).

Collectives™ on Stack Overflow

Correct OpenAPI specification for returning HTML from a API call

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related