How to express "arbitrary JSON" in swagger-spec?

Question

Let's say I have a REST service that can accept any arbitrary JSON in the request body. How do I model this using swagger-spec?

I thought about Model Objects, but I could only think to wrap the arbitrary JSON (as a string) within a container JSON object, like {"payload": "{ some JSON object serialized to a string }"}, which isn't really useful.

Or, is there some other way to express that an endpoint can receive arbitrary JSON in the request body?

Answer 1

Swagger tries to be deterministic when it comes to APIs, so what you're asking is not directly supported.

The only way I can think of to achieve what you want is to set the "consumes" property to "application/json" and add a "body" parameter of type string. This would in theory say that only JSON should be sent, but in effect, any string could be sent.

Also, this may break some third party tools if they'd try to convert to string to a JSON object before sending it to the server.

Answer 2

Model the request's body payload as parameters with schema of just "type": "object". The swagger UI editor will then prompt the user with a large textarea containing {} which they can populate with a JSON object.

"/endpoint": {
      "post": {
        "parameters": [
          {
            "description": "Arbitrary JSON object payload",
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "type": "object"
            }
          }
        ]
      }