@shapediver/util.oas3

util.oas3

This utility-library enables to generate a OpenAPI v3 Specification (OAS) that has been defined by using JsDoc-like comments. The library also allows merging multiple existing OAS specifications. This enables the usage of partial specifications in separate projects and linking them dynamically later on.

Comments

Individual elements of the specification are created via JSDoc-like comments which the structure @swagger {<path>} <name> <value>.\

Notes:

• Only /** */-comments starting with the @swagger-tag are processed.
• Multiple tags can be used inside a single comment.
• When passing an object or an array as value, watch strict validation of JSON-objects!
• OpenAPI v3 features like inheritance or $ref can be used normally.
• Object and Array-values can be created and extended via multiple comments (see examples 2 and 3).
• When an array-value is extended via multiple comments, similar elements are ignored (see example 2).
• When an object-value is extended via multiple comments, similar properties are overwritten (see example 3).

Example 1

The following example

/**
 * @swagger {components.schemas} Foo {
    "description": "Foo or Bar",
    "type": "string",
    "enum": [ "''", "foo", "bar" ]
  }
 */

results in

{
  "components": {
    "schemas": {
      "Foo": {
        "description": "Foo or Bar",
        "type": "string",
        "enum": [
          "''",
          "foo",
          "bar"
        ]
      }
    }
  }
}

Example 2

In this example, an array is created and extended via multiple comments. However, the similar element "bar" is ignored:

/**
 * @swagger {components.schemas.Foo} required [ "foo", "bar" ]
 * @swagger {components.schemas.Foo} required [ "bar", "baz" ]
 */

Result:

{
  "components": {
    "schemas": {
      "Foo": {
        "required": [
          "foo",
          "bar",
          "baz"
        ]
      }
    }
  }
}

Example 3

In this example, an object is created, extended and partly overwritten via multiple comments:

/**
 * @swagger {components.schemas} Foo {
    "foo": "bar"
    "baz": "qux"
  }
 * @swagger {components.schemas} Foo {
    "baz": "bar"
  }
 */

Result:

{
  "components": {
    "schemas": {
      "Foo": {
        "foo": "bar",
        "baz": "bar"
      }
    }
  }
}

Example 4

This example shows how to specify and extend an object inside an array of objects:

/**
 * @swagger {components.schemas} Foo {
     "allOf": [
       { "$ref": "#/components/schemas/Bar" },
       { "type": "object" }
     ]
   }
 * @swagger {components.schemas.Foo.allOf.[1].properties} something {
     "type": "number"
   }
 */

Result:

{
  "components": {
    "schemas": {
      "Foo": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Bar"
          },
          {
            "type": "object",
            "properties": {
              "something": {
                "type": "number"
              }
            }
          }
        ]
      }
    }
  }
}

Usage

The library can be installed globally or as a npm dependency and run via a CLI.

# List all commands and their options
./node_modules/.bin/sd-oas3 --help

# When adding ./node_modules/.bin to $PATH, the command can be invoked directly
sd-oas3 --help

# Generate a new specification
sd-oas3 generate -s ./src/ -e ts -o ./swagger.json

# Merge two existing specifications and write the result into a new file
sd-oas3 merge -s ./specA.json ./specB.json -f ./res.json

# Merge three existing specifications into another specification
sd-oas3 merge -s ./specA.json ./specB.json ./specC.json -t ./target.json