Skip to main content

Quick Start Guide

This guide will help you get started with itdoc quickly by walking through a simple example using Express.js.

tip

If you're using a framework other than Express, please refer to the Framework Guide for additional instructions.

Prerequisites​

  • Node.js (version 20 or higher)
  • A test runner (Jest or Mocha)
  • Express.js application (for the example)

Installation​

Install itdoc using your package manager of choice:

pnpm install itdoc --save-dev

Basic Usage​

Let's create a simple API documentation for an Express application.

1. Create an Express Application​

Create a simple Express application (or use your existing one):

const express = require("express")
const app = express()

app.use(express.json())

app.post("/signup", (req, res) => {
    const { username, password } = req.body

    if (!username) {
        return res.status(400).json({ error: "username is required" })
    }

    if (password && password.length < 8) {
        return res.status(400).json({ error: "password must be at least 8 characters" })
    }

    return res.status(201).json({ message: "User created successfully" })
})

module.exports = app

2. Create a Test File​

Create a test file that uses itdoc to document your API:

const app = require("./expressApp")
const { describeAPI, itDoc, HttpStatus, field, HttpMethod } = require("itdoc")

describeAPI(
    HttpMethod.POST,
    "/signup",
    {
        summary: "User Registration API",
        tag: "Auth",
        description: "Registers a new user with username and password.",
    },
    app,
    (apiDoc) => {
        itDoc("Successful registration", () => {
            return apiDoc
                .test()
                .req()
                .body({
                    username: field("Username", "testuser"),
                    password: field("Password", "Password123!"),
                })
                .res()
                .status(HttpStatus.CREATED)
                .body({
                    message: field("Success message", "User created successfully"),
                })
        })

        itDoc("Missing username returns error", () => {
            return apiDoc
                .test()
                .req()
                .body({
                    password: field("Password", "Password123!"),
                })
                .res()
                .status(HttpStatus.BAD_REQUEST)
                .body({
                    error: field("Error message", "username is required"),
                })
        })
    },
)

3. Run Tests​

Configure your test runner. Then run:

pnpm test

If the documentation is not generated correctly, check the Integration with Test Runner guide.

4. Generate OpenAPI Documentation​

When you run the tests, an OpenAPI document will be automatically generated in the output/oas.json file in your project root directory. This file is generated based on the API documentation information written in your test code.

5. Additional Configuration (package.json)​

You can configure additional settings, such as the output directory and document metadata, by adding an itdoc field to your package.json file.

package.json
{
    // ... other package.json configurations
    "itdoc": {
        "output": "output", // Directory where the OpenAPI document will be generated (default: output)
        "document": {
            "title": "My API Documentation", // Document title
            "description": "Detailed description of my API." // Document description
        }
    }
}

For more detailed configuration options, refer to the Configuration Guide.

What's Next?​