API Reference

This page provides a comprehensive reference to the core APIs of itdoc.

Core Functions

describeAPI()

The main function to define and document an API endpoint.

function describeAPI(
    method: HttpMethod,
    path: string,
    options: ApiDocOptions,
    app: Express.Application | any,
    testCallback: (apiDoc: RootBuilder) => void,
): void

Parameters:

• method: The HTTP method of the API endpoint (GET, POST, PUT, DELETE, etc.)
• path: The URL path of the API endpoint
• options: Configuration options including summary, tag, and description
• app: The Express application instance or any other application to test against
• testCallback: A callback function that defines the test cases for this API endpoint

Example:

describeAPI(
    HttpMethod.GET,
    "/users",
    {
        summary: "Get all users",
        tag: "Users",
        description: "Returns a list of all users in the system",
    },
    app,
    (apiDoc) => {
        // Define test cases here
    },
)

itDoc()

Defines a test case within a describeAPI block.

function itDoc(description: string, testFn: () => RootBuilder | Promise<RootBuilder>): void

Parameters:

• description: A description of the test case
• testFn: A function that returns a RootBuilder instance defining the test

Example:

itDoc("Successfully retrieves all users", () => {
    return apiDoc
        .test()
        .req()
        .queryParam({ page: 1, limit: 10 })
        .res()
        .status(HttpStatus.OK)
        .body({
            users: field("List of users", [{ id: 1, name: "John" }]),
            total: field("Total count", 1),
        })
})

field()

Marks a field in the request or response body with a description for documentation purposes.

function field<T>(description: string, value: T): T

Parameters:

• description: A description of the field
• value: The value for the field in the test

Example:

// In a request
.body({
  username: field('User login name', 'john_doe'),
  password: field('User password', 'securePassword123'),
})

// In a response
.body({
  id: field('User ID', 123),
  token: field('Authentication token', 'eyJhbGciOi...'),
})

Enumerations

HttpMethod

Enum representing HTTP methods.

enum HttpMethod {
    GET = "get",
    POST = "post",
    PUT = "put",
    DELETE = "delete",
    PATCH = "patch",
    HEAD = "head",
    OPTIONS = "options",
}

HttpStatus

Enum representing HTTP status codes.

enum HttpStatus {
    OK = 200,
    CREATED = 201,
    ACCEPTED = 202,
    NO_CONTENT = 204,
    MOVED_PERMANENTLY = 301,
    FOUND = 302,
    BAD_REQUEST = 400,
    UNAUTHORIZED = 401,
    FORBIDDEN = 403,
    NOT_FOUND = 404,
    METHOD_NOT_ALLOWED = 405,
    CONFLICT = 409,
    INTERNAL_SERVER_ERROR = 500,
    NOT_IMPLEMENTED = 501,
    BAD_GATEWAY = 502,
    SERVICE_UNAVAILABLE = 503,
    // ... (other status codes)
}

Builder Classes

RootBuilder

The main builder class for creating API test cases.

Key Methods:

• test(): Initializes a new test case
• req(): Returns a RequestBuilder to configure the request
• res(): Returns a ResponseBuilder to configure the expected response
• prettyPrint(): Enables pretty printing of test results

RequestBuilder

Builder for configuring the request part of a test.

Key Methods:

• body(body: object): Sets the request body
• header(headers: object): Sets request headers
• pathParam(params: object): Sets path parameters
• queryParam(params: object): Sets query parameters
• expectStatus(status: HttpStatus): Sets the expected response status

ResponseBuilder

Builder for configuring the expected response part of a test.

Key Methods:

• status(status: HttpStatus): Sets the expected response status code
• body(body: object): Sets the expected response body
• header(headers: object): Sets the expected response headers