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.

Have a look at the parser

This editor is based on the TSSG Parser. You can have a look at https://github.com/tauqeernasir/tssg-syntax-parser

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)g
• 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,
    }
}

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[]
}

or something more complex as follow:

{
    data: {
      _id: string,
      name: string,
      age: number
    }[]
}

Look, how simple it is to define array of string and array of object in a few lines.

Above first 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,
        }
    }[]
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Tauqeer Nasir 💻 🚧 📖 💡

Akshat Sharma 💻 📖 💡 🚧

Ming Hu 💻 💡 🚧