Creating OpenAPI Specs

zSYNC allows for the creation of complete OpenAPI documentation for your API, without having to write the code yourself.

We’re using screenshots from the publicly available Swagger Editor, an open-source tool maintained by SmartBear, licensed under the Apache License 2.0.

It’s a two step process:

1. Create a zSYNC pipeline, per required endpoint, and add the endpoint info to each pipeline’s Starter Worker.

2. Use the zSYNC OpenAPI generator to automatically compile all the desired endpoints into a single specification file.

How to Create OpenAPI Specs with zSYNC:

1. Configure Endpoint Information in the Start Worker

Create a new zSYNC pipeline and open the Start Worker, which is automatically created upon saving.

Add the endpoint identifier (path) for your HTTP endpoint, then begin typing an identifier into the API config field. Choose “Create and edit” to edit the endpoint specifications.

Enter the basic HTTP config info for the endpoint. The shortname, request group, request type and payload/response type are the most essential info.

2. Add Data

To do this, there are two main options:

1. Take the easy way out, paste some sample data into the UI, and avoid specifying all data fields individually.
   Advantage: fast, simple, great for creating quick demo specs.
   Disadvantage: the generated specs will not be sufficient for auto-generating code from, or for developers to get complete development details from.

2. Take the time to specify each payload and response field individually.
   Advantage: creates thorough developer specifications: sufficient for auto-generating code from.
   Disadvantage: requires more time and effort.

Take your pick:

2.1. Quick Example Data

In the Examples table, add a line. Create and save your mock data there.

If using JSON format data, be careful to remove trailing commas.

Then, to make sure that the payload is registered (if your endpoint has a payload), add an empty payload scheme. No need to edit it.

2.2. Full Data Specifications

Docs for configuring a full data specification coming soon

3. Generate OpenAPI Specs

Navigate to zSYNC’s OpenAPI Spec generator.

Fill in the API specification details, including selecting which pipelines you’d like to include specifications from. Then click generate spec.

4. View the Generated Specs in a Swagger UI

To view, explore, or test out the generated API specs, copy the specs from zSYNC and paste them a Swagger editor like this one.

OpenAPI specs are also useful for auto-generating client or server code, creating API test suites, and more. We’re not sponsored, but we do like open source! Here’s a list of lots of the available OpenAPI toolings.