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