Updated styling for new API Explorer

ReadMe's API explorer has had a tumultuous past with supporting some of the more exotic parts of JSON Schema. We built it at a time when Swagger/OAS was not as widely used as it is today and creating your APIs was solely done from within our Dashboard.

Manually documenting an api in ReadMe's dash

This is still 100% supported and is a very popular way of documenting your endpoints in ReadMe. However, allowing people to upload Swagger and OAS files directly to us means it is possible to use JSON Schema to document what parameters your APIs accept. This includes (but is not limited to) the following types:

  • objects
  • nested objects
  • named arrays/objects
  • arrays of objects
  • arrays of primitives
  • top level arrays and primitives

Out with the old

Nested objects

Our legacy explorer did not provide support for objects nested more than three levels deep:

"object": {
  "type": "object",
  "properties": {
    "nested object": {
      "type": "object",
      "properties": {
        "nested object": {
          "type": "object",
          "properties": {
            "nested object": {
              "type": "object",
              "properties": {
                "nested object": {
                  "type": "object",
                  "properties": {
                    "string": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

would be rendered as:

nested objects showing missing string

Which would completely not render the string at the end of the chain.

Arrays

We used a tag builder module to deal with arrays of primitives:

"array": {
  "type": "array",
  "items": {
    "type": "string"
  }
}

array of primitive values

Arrays of booleans also used this tag builder, for which we just excluded any string value that did not exactly match "true" or "false".

For nested objects, we built a rather crude array builder:

"array of objects": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "string": {
        "type": "string"
      }
    }
  }
}

array builder for nested objects

This also does not work for arrays with nested objects inside of them.

Top level values

Top level (nameless) strings, arrays, integers, objects etc. None of these worked and all rendered with no input form.

In with the new

Here's an overview showing of all of the new styled elements:

screenshot of new explorer

Nested objects

Nested objects will now render as nested as you want them to go:

nested objects

Arrays

Arrays of primitives now work better, with correctly typed <input> elements:

array of strings

Arrays of booleans work using <select> elements:

array of booleans

Top level values

We now support top level arrays and top level primitives.

top level array
top level primitive

Conclusion

Our API Explorer is open source, if you find any types that we do not support very well, please email support@readme.io or checkout our test OAS file we use to test these types.

Stay In-Touch

Want to hear from us about APIs, documentation, DX and what's new at ReadMe?