Developer Portal
OpenAPI Specifications
Zuplo natively uses the OpenAPI specification to power both the gateway routing
and Developer Portal documentation. Your OpenAPI file (contained within your
project's config
folder and ending in .oas.json
) is used to automatically
generate stripe-quality API Reference documentation. By enriching your OpenAPI
file with additional properties, you directly enable more content show up in the
Developer Portal.
Read more about OpenAPI and all the possibilities.
Supported OpenAPI Versions#
Zuplo has full support for features within OpenAPI 3.1. If you are still on OpenAPI 3.0, then most features will still be supported within the Developer Portal. OpenAPI 2.x / Swagger or earlier is not supported at this time. There are multiple solutions to convert your OpenAPI 2.x document - including CLI, and API.
Handling Multiple OpenAPI Files#
Your project may utilize multiple OpenAPI files to power your gateway. The Developer Portal is equipped to handle this - allowing users to navigate between documentation for each OpenAPI spec. You can even customize the content displayed on each OpenAPI spec.
JSON Schemas#
You can embed your JSON Schemas directly into your OpenAPI document on each
endpoint, or if you want to share them within, you can put them in the
components
section and use a reference, example:
"responses": { "200": { "description": "A list of todos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoListObject" } } } } },
You can also reference an external schema (you might store this in the schemas
folder of your project, e.g.
"400": { "description": "Schema validation error", "content": { "application/json": { "schema": { "$ref": "../schemas/schema-validation-error.json" } } } }
Providing Examples#
The Developer Portal allows you to configure the displayed examples for properties like parameters, request bodies, and responses. There are several different ways to specify an example in OpenAPI, so here's the order of precedence we use:
- The
example
property, found on Media Type Object(ex. request and response bodies) and Parameter Object(ex. Params and response headers). - The first
examples
entry, found on the Media Type Object and Parameters Object. - If a schema is specified, the first entry in the schema's
examples
. - The
example
property on the schema. - The
default
property on the schema. - If none of the above are present, and
generateExamples
istrue
indev-portal.json
, then we will generate an example using the provided schema