SWAGGER-DEFINER

Document your api with ease

. . . . . . . .

SWAGGER-DEFINER is a simple node.js library for defining Swagger 2.0 Spec.

• Simple API
• Built-in validation
• Use TypeScript Annotations or pure Javascript

Installation

$ npm install swagger-definer

Usage examples

// swagger.js
export const swg = new Swagger("petstore.swagger.io", "/v2")
swg.tag("user", "User operations")
swg.security("jwt", {
  type: "apiKey",
  name: "Authorization",
  in: "header",
  description: "JWT Auth"
})
 
require("UserModel.js")
require("UserRoutes.js")
 
swg.validate().then(spec => { // Or simply call toJson() for skiping validation
    console.log(spec) // Or write to file
})

// UserModel.js
import { swg } from "swagger.js"
 
// Using plain JS
swg.definition("User")
  .property("name", "string", "User name", true, "Igor")
class User {
    name: string
}
 
// Or using TypeScript annotations
const { definition, property } = swg.annotations()
 
@definition("User")
class User {
  @property("name", "string", "User name", true, "Igor")
  name: string = "Igor"
}

// UserRoutes.js
import { swg } from "swagger.js"
 
// Using plain JS
swg.path("/user", "post", "createUsers", ["user"], "Create user")
  .parameter("body", "body", "[#/definitions/User]", true, "Array of users")
  .response("200", "Success", "string")
  .response("default", "Success", "string")
  .security("jwt")
function createListOfUsersAction() {
  console.log('User created')
}
 
// Or using TypeScript annotations
const { path, parameter, response, security } = swg.annotations()
 
// Annotations not working without class
class UserController {
 
  @path("/user", "post", "createUser", ["user"], "Create user")
  @parameter("body", "body", "#/definitions/User", true, "User instance")
  @response("200", "Success", "string")
  @response("default", "Error", "string")
  @security("jwt")
  create() {
    console.log('User created')
  }
 
}

For more examples see: https://github.com/Sujimoshi/swagger-definer/tree/master/examples

About types

Definition.prototype.property(
    name: string, // Name of property
    type: string | Schema, // Type of property. allowed values:
        // {} - Swagger Schema object
        // "#/definitions/Model" - parses to "ModelReference" Schema
        // "[#/definitions/Model]" - parses to array of "ModelReferences" Schema
        // "[type]" - parses to array of "types" Schema
        // "type" - parses to parameter of "type" Schema
    description: string = "", // Description
    required: boolean = true, // Is required
    example: any = "" // Example value for UI
)

Types parsing table:

Common Name	type	format	Comments
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
float	number	float
double	number	double
string	string
byte	string	byte	base64 encoded characters
binary	string	binary	any sequence of octets
boolean	boolean
date	string	date	As defined by full-date - RFC3339
dateTime	string	date-time	As defined by date-time - RFC3339
password	string	password	Used to hint UIs the input needs to be obscured.