TSSG - The Swagger Schema Generator

Write schema in an easy, concise and short way.

Vision and Motivation

Writing OpenAPI Schema can be tiresome and time wasting task if you write a lot of API Documentation. Updating existing Schema can also be cumbersome and confusing especially when project grows to hundreds of APIs. TSSG is here to help you write schema in an easy, clean and concise way. We have proposed a new and easy to understand Syntax/Grammar for this. It allows you to write less and get full OpenAPI Schema without writing and repeating same line again and again.

Project Roadmap

Our aim is to build a tool that helps you in splitting your APIs Schemas and Endpoints Definitions into separate files so that it's easy to maintain and update/edit the target APIs.

Below is our roadmap:

TSSG Syntax Parser (Alpha Version released)
TSSG to OpenAPI Transformer (Alpha Version released)
TSSG Editor (Alpha Version released)
OpenAPI to TSSG Syntax Transformer (WIP)
TSSG CLI (WIP)

How to use?

Consider the following object Schema of User:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    },
    "email": {
      "type": "string"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "zipcode": {
          "type": "string"
        }
      }
    }
  }
}

The above schema has a lot of repetition and if the schema is more complex that have nested object or array of object, it gets more complex to write.

On the other hand, with TSSG, above schema can be written as:

{
    name: string,
    age: number,
    email: string,
    address: {
        street: string,
        city: string,
        country: string,
        zipcode: string,
    }
}

We hope, we don't need to explain above syntax. It's already understandable and easy to type and read.

You only need to mention the type of the property and it will be tranformed to { "type": "string" } form.

Supported Types

Following data types are support as of now:

string
number
integer
boolean
{} (shorthand for object type)
[] (shorthand for array)

More Examples

Required Properties

Let's take the above example again, and add some properties as required.

{
  "type": "object",
  "required": ["name", "email", "address"],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    },
    "email": {
      "type": "string"
    },
    "address": {
      "type": "object",
      "required": ["country"],
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "zipcode": {
          "type": "string"
        }
      }
    }
  }
}

In the above schema, we have name, email and address as required property and inside the address object we have country as required.

To write the above schema, you can simply do the following:

{
    name: !string,
    age: number,
    email: !string,
    address: !{
        street: string,
        city: string,
        country: !string,
        zipcode: string,
    }
}

You can mark a property as required by using ! (exclamation mark) in front of data type. Above mentioned syntax will produce the exact same OpenAPI Schema shown above example.

Notice ! in the start of address value.

Arrays

Consider this simple example which accepts data property of type array of string.

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Above schema can be written in TSSG as follows:

{
    data: [string]
}

Look, how simple it is to define array of string in one simple line.

You can also mark data property as required using ! sign.

{
    data: ![string]
}

Above TSSG syntax will produce following Schema:

{
  "type": "object",
  "required": ["data"],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Array of Objects

Consider the following schema:

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "object",
            "required": ["country"],
            "properties": {
              "street": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "zipcode": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Above schema can be written in TSSG as follow:

{
    data: [{
        name: string,
        age: number,
        email: string,
        address: {
            street: string,
            city: string,
            country: string,
            zipcode: string,
        }
    }]
}

If data property is required, just mark that required using ! sign.

Enums

You can use the enum keyword to specify possible values of a request parameter or a model property. For example, consider the following schema:

{
    "type": "object",
    "properties": {
        "colors": {
            "type": "string",
            "enum": [
                "red",
                "green",
                "blue"
            ]
        }
    }
}

Above schema can be written in TSSG as follows:

{
    colors: enumOf(string, "red", "green", "blue"),
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Tauqeer Nasir}
💻 🚧 📖 💡

_{Akshat Sharma}
💻 📖 💡 🚧

_{Ming Hu}
💻 💡 🚧

jbactad / tssg-editor