README

api ➡️ doc ➡️ validator

Annotations

@url
@baseUrl
@params
@query
@body
@response
@namespace
@schema
@call

Parameters of annotations

METHOD
CODE
path
OBJECT_NAME
json-schema
object-method-call

Usage

cli
API client
Express middleware
Universal middleware
Swagger OpenAPI
Validation errors handling
Config

@url

@url [METHOD] path

/**
 * Some description
 * @url POST /path/:param
 */

@baseUrl

@baseurl path

/**
 * @baseUrl /v1
 */

/**
 * @url /users
 */

Final url will be /v1/users

@params

Validate parameters of @url path

@params [OBJECT_NAME =] json-schema|OBJECT_NAME

/**
 * @url GET /users/:id
 * @params {
 *   # some description for `id` (usefull for OpenApi)
 *   id: number,
 * }
 * @call users.get(id)
 */

or with OBJECT_NAME assign for future use

/**
 * @url GET /users/:id
 * @params User = {
 *   id: number, // description for `id`
 * }
 */

or use an external schema as root schema

/**
 * @url GET /users/:id
 * @params User
 */

or extend external schema

/**
 * @url GET /users/:id
 * @params {
 *   ...User,
 *   name: string,
 * }
 */

@query

Validate @url query parameters

@query [OBJECT_NAME =] json-schema|OBJECT_NAME

/**
 * @url GET /users
 * @query {
 *     id: number,
 * }
 * @call users.get(id)
 */

Example of valid request GET /users?id=1

Names of fields in @params and query should be different to use them in @call

/**
 * @url GET /users/:id
 * @params {
 *     id: number,
 * }
 * @query {
 *     name: string,
 * }
 * @call users.get(id, name)
 */

@body

@body [# Description] [OBJECT_NAME =] json-schema|OBJECT_NAME

/**
 * @body {
 *   id: number,
 *   name: string,
 * }

 * @body User = {
 *   id: number,
 *   name: string,
 * }

 * @body 
 * # Some body description
 * User = {
 *   id: number,
 *   name: string,
 * }
 */

@response

Response http code and validation of response body.

@response [CODE] [# Description] [OBJECT_NAME =] json-schema|OBJECT_NAME

Response for 200 code

/**
 * @response {
 *   id: number,
 *   name: string,
 * }
 */

Validators for different codes of same request

/**
 * @response 200 {
 *   id: number,
 *   name: string,
 * }
 * @response 500 
 * # Some description
 * {
 *   message: string,
 * }
 */

@namespace

Shortcut @ns

Word used to filter validators in target file.

/**
 * Namespace for this validator will be "default"
 * 
 * @url POST /users
 * @body {id: number}
 */

/**
 * @namespace test
 * @url POST /test-success
 * @response 2xx {success: boolean}
 */

/**
 * @ns test
 * @url POST /test-error
 * @response 5xx {error: boolean}
 */

Example of generation express middleware with only test validators

npx adv -c path/to/config.json -n test -e ./test-validator.js

@schema

Define the new schema for future usage

@schema OBJECT_NAME = json-schema|OBJECT_NAME

/**
 * @schema User = {
 *     id: number,
 *     name: string,
 * }
 */

or just to make shorter schema name

/**
 * @schema User = SomeVeryLongSchemaName
 */

@call

You should provide valid js code of method call. This code will be used in your API tests.

@call object-method-call

/**
 * @call object.method(param1, param2)
 */

METHOD

HTTP request method. Default is config.defaultMethod

GET|POST|PUT|DELETE|HEAD|OPTIONS

CODE

HTTP response code. Default is config.defaultCode

Formats:

200 regular code number
2xx any code between 200 and 299
200 - 400 any code between 200 and 400
200 || 3xx || 400 - 500 or expression

Example

/**
 * @response 2xx || 301 User = {id: number}
 */

path

URL pathname. For path parsing used path-to-regexp lib.

Parameters like :id can be used in @call as parameter of method call with same name.

/**
 * @url GET /users/:id(\d+)
 * @call users.get(id)
 */

OBJECT_NAME

Any valid js object name like objectName or with field of any deep objectName.fieldName.field

json-schema

Object that describes how validate another object. For validation used ajv.

For syntax details see adv-parser

object-method-call

Uniq sample of JavaScript code with some method call of some object, which will be generated for testing purposes. In method call you can use named parameters from @url

/**
 * @url GET /users
 * @call users.get()
 */

/**
 * @url GET /users/:id
 * @call users.get(id)
 */

/**
 * @url POST /users/:id/settings
 * @call users.setSettings(id)
 */

/**
 * @url POST /users/:id/settings
 * @call users.settings.update(id)
 */

There can be any number of nested objects and any method name. Only names of parameters should be equal.

CLI

with npx

npx adv -c path/to/config.json

Parameters:

  -c, --config <path> path to config json file
  -i, --include <path> path to source file
  -a, --api-client <path> generate api client
  -b, --base-url <url> default Api.baseUrl
  -e, --express <path> generate express middleware validator
  -o, --open-api <path> generate Swagger OpenAPI v3 json
  -j, --json <path> generate endpoints json
  -n, --namespace <namespace> generate validators only with this namespace or comma separated namespaces
  -M, --default-method <method> default @url METHOD
  -C, --default-code <code> default @response CODE
  -S, --default-schemas <path> path to js file with default schemas
  -T, --jsdoc-typedefs <boolean> generate typedef, default true
  -R, --jsdoc-refs <boolean> use references to jsdoc @typedef or replace them with reference body, default true
  -I, --include-jsdoc <boolean> include to endpoints jsdoc annotations, default false
  -P, --extra-props <boolean> value for ajv "object" additionalProperties, default false

API client

Install in to your project packages ajv, ajv-formats (optional if you not using String patterns), request (if you don't like request then you will need to implement Api.request) and path-to-regexp. Client will depend on them.

Generate the API client with npx adv -c path/to/config.json -a path/to/your/app/api-client.js

Example

/**
 * @url POST /users
 * @body User = {id: number, name: string}
 * @response 200 User
 * @call addUser()
 */

/**
 * @url GET /users/:id
 * @params {id: number}
 * @response 200 User
 * @call users.get()
 */

Generated api-client.js will export class Api.

const Api = require('./path/to/your/app/api-client.js');
const client = new Api(/* "https://new.base.url" optionaly, default is Api.baseUrl */);

console.log(Api.baseUrl); // value from config.baseUrl or --base-url cli option
console.log(Api.endpoints); // parsed endpoints from comments

// optionaly
Api.getAjv = () => createYourAjvInstance();
Api.request = function ({
   method, 
   url, 
   params /* url params like /:id */, 
   query, 
   body, 
   endpoint /* object from Api.endpoints */, 
   context /* Api class instance */
}) {
    return sendRequestReturnPromise(context.baseUrl + url);
}
Api.errorHandler = function (err) {
    console.error(err);
    
    throw err;
};
// --

await client.addUser({id: 1, name: 'Test'});

client.users.get({id: 1} /* or just 1 if @params has only one parameter */)
  .then(user => {
     console.log(user.name);
     console.log(client.requestCookieJar); // @see request.jar() https://github.com/request/request#examples
  })
  .catch(err => {
     // @see Validation errors handling
  });

Express middleware

Install in to your project packages ajv, ajv-formats (optional if you not using String patterns) and path-to-regexp. Middleware depends on them.

Generate the middleware with npx adv -c path/to/config.json -e path/to/your/app/validator.js

Then add middleware to your express app

const validator = require('./path/to/your/app/validator.js');

// optionaly
validator.getAjv = () => createYourAjvInstance();
// --

app.use(validator);
app.post('...', (req, res) => {});
app.use(function (err, req, res, next) {
    if (err instanceof validator.RequestValidationError) {
        // @see Validation errors handling
    }
    else if (err instanceof validator.ResponseValidationError) {
       // @see Validation errors handling
    }
    else {
        next(err);
    }
    
    // or use base class
   
    if (err instanceof validator.ValidationError) {
       // @see Validation errors handling
    }
    else {
       next(err);
    }
});

Universal middleware

Generate the middleware with npx adv -c path/to/config.json -e path/to/your/app/validator.js

Then add it to your app

const validator = require('./validator.js');

function sendMessage(path, data) {
    try {
       var validateResponse = validator({
          url: path,
          body: data,
       });
    }
    catch (err) {
       // @see RequestValidationError
    }
    
    return ajax(path, data).then(function (result) {
        if (validateResponse) {
           try {
              validateResponse(result);
           }
           catch (err) {
              // @see ResponseValidationError
           }
        }
        
        return result;
    });
}

Swagger OpenAPI

Generate Swagger OpenAPI v3 json with npx adv -c path/to/config.json -o path/to/open-api.json

Validation errors handling

Both Api class and middleware exports three classes:

ValidationError - base class, extends Error
RequestValidationError - class of request validation error, extends ValidationError
ResponseValidationError - class of response validation error, extends ValidationError

let err; // error from api client or middleware validator
let context; // Api class or middleware

if (err instanceof context.RequestValidationError) {
   console.log(err.message);
   console.log(err.property); // query | params | body
   console.log(err.errors); // @see https://github.com/ajv-validator/ajv/blob/master/docs/api.md#validation-errors
}
else if (err instanceof context.ResponseValidationError) {
   console.log(err.message); // "Invalid response body"
   console.log(err.errors); // @see https://github.com/ajv-validator/ajv/blob/master/docs/api.md#validation-errors
}

// or use base class

if (err instanceof context.ValidationError) {
   console.log(err.message);
   console.log(err.property);
   console.log(err.errors);
}

Config

include array of paths to files relative to config path, glob pattern used
exclude array of paths to files to be excluded
defaultMethod overwrites default METHOD. Default is GET
defaultCode overwrites default CODE. Default is 200
defaultSchemas same as --default-schemas <path>
jsdocTypedefs generate @typedef for each named schema. Default is true
jsdocRefs use references to @typedef or replace them with reference body. Default is true
apiClient same as --api-client <path>
json same as --json <path>
express same as --express <path>
openApi same as --open-api <path>
namespace same as --namespace <namespace>
includeJsdoc same as --include-jsdoc <boolean>
extraProps same as --extra-props <boolean>

All paths are relative to config file location.

Example

{
  "include": [
    "src/**/*.js",
    "src/**/*.php"
  ],
  "exclude": [
    "src/tests"
  ],
  "defaultMethod": "POST",
  "defaultCode": "2xx || 301"
}

api-doc-validator

Usage no npm install needed!

README

api ➡️ doc ➡️ validator

Annotations

Parameters of annotations

Usage

@url

@baseUrl

@params

@query

@body

@response

@namespace

@schema

@call

METHOD

CODE

path

OBJECT_NAME

json-schema

object-method-call

CLI

API client

Express middleware

Universal middleware

Swagger OpenAPI

Validation errors handling

Config