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.

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

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
        }
    }
}

This configuration allows you to control the basic information of the generated OpenAPI document and change the output file location.

For more detailed examples, check out the examples in the GitHub repository.

What's Next?​