itdoc

itdoc is a Node.js tool for automatically generating API documentation based on your test code.
Hate writing docs? Let your tests do it. Your API docs stay in sync—no surprises, ever.

A perfect alternative to swagger-jsdoc and swagger-ui-express.

• Test-based Documentation: itdoc generates documentation by directly extracting API request and response examples from your test code, ensuring your documentation accurately reflects your API behavior.
• Multiple Documentation Formats: Export documentation in various formats, such as OpenAPI Specification, Markdown, and HTML (Redoc-style).
• Supports Various Frameworks: Compatible with popular Node.js frameworks like Express, NestJS, fastify.
• Easy to Use Without Complex Configuration: Generate documentation effortlessly by writing tests alone. (Optional configuration is available)

Installation

npm install itdoc --save-dev

Documentation

Full documentation for itdoc can be found on the official website.

you can contribute to improving our documentation by submitting a PR to our docs folder.

Examples

We have several examples available in the examples directory. Here's a simple Express example to help you get started.

import { describeAPI, itDoc, field, HttpMethod, HttpStatus } from "itdoc"

// Assume you have an Express app
const targetApp = app

describeAPI(
    HttpMethod.POST,
    "/signup",
    {
        name: "Sign Up API",
        tag: "Auth",
        summary: "Receives a username and password from the user to perform sign-up.",
    },
    targetApp,
    (apiDoc) => {
        itDoc("Successful sign-up", () => {
            return apiDoc
                .test()
                .req()
                .body({
                    username: field("Username", "penekhun"),
                    password: field("Password", "P@ssw0rd123!@#"),
                })
                .res()
                .status(HttpStatus.CREATED)
        })

        itDoc("Fails to sign up if username is not provided.", async () => {
            await apiDoc
                .test()
                .req()
                .body({
                    password: field("Password", "P@ssw0rd123!@#"),
                })
                .res()
                .status(HttpStatus.BAD_REQUEST)
                .body({
                    error: field("Error message", "username is required"),
                })
        })
    },
)

• If you are using Express, please refer to the Quick Start Guide.
• If you are using NestJS, please refer to the Quick Start Guide and NestJS guide.
• If you are using fastify, please refer to the Quick Start Guide and fastify guide.

Running Tests

Since describeAPI() and itdoc() integrate seamlessly with testing frameworks like Jest and Mocha, you can simply use your existing test commands such as mocha . or jest . without any changes.

Contributing

We welcome contributions! Please open an issue or submit a pull request. See CONTRIBUTING.md for guidelines.

License

This project is licensed under the terms of the Apache 2.0 License.