anyspec

Anyspec is a DSL (Domain Specific Language) for writing API specs with main compilation target to Openapi (swagger).

The main problem we are trying to solve is the verbosity of open API.

• Write less code - get rid of boileprate in your daily routine.
• Enforce best practices - use predefined or write your own rules for specs.
• Prettify (WIP) - format your code without pain.
• Compilation (WIP) - the result json is fully compatible with openapi specification.

Built by 2 engineers for Osome with love ❤️

We are hiring

Watch in action

Before

// **Some description**
@token POST /documents DocumentNew
    => { document: Document }

DocumentNew {
  name: s, 
}

DocumentNew {
  id: i,
  name: s,
}

After

{
  "swagger": "2.0",
  "info": {
    "title": "Test API",
    "version": "{{version}}"
  },
  "host": "{{host}}",
  "basePath": "/api/v2",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "token": {
      "name": "X-Access-Token",
      "type": "apiKey",
      "in": "header"
    }
  },
  "paths": {
    "/documents": {
      "post": {
        "summary": "**Some description**",
        "description": "**Some description**",
        "operationId": "POST--documents",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "document": {
                  "$ref": "#/definitions/Document"
                }
              },
              "required": [
                "document"
              ]
            }
          }
        },
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/DocumentNew"
            },
            "in": "body"
          }
        ]
      }
    }
  },
  "definitions": {
    "DocumentNew": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}

Table of contents

List of rules

Watch docs

Inspiration section

The main idea of library - DSL on top of openapi comes from tinyspec. The syntax constructions comes from tinyspec too.

Also authors were inspired and use a lot of findings and ideas from:

• Graphqljs implementation
• python lexer and parser

License

The code in this project is released under the MIT License.