Quick Start Guide
This guide will help you get started with itdoc quickly by walking through a simple example using Express.js.
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
- yarn
- npm
pnpm install itdoc --save-dev
yarn add -D itdoc
npm 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):
- JavaScript
- TypeScript
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
import express, { Request, Response } from "express"
const app = express()
app.use(express.json())
app.post("/signup", (req: Request, res: Response) => {
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" })
})
export default app
2. Create a Test File
Create a test file that uses itdoc to document your API:
- JavaScript
- TypeScript
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"),
})
})
},
)
import app from "./expressApp"
import { describeAPI, itDoc, HttpStatus, field, HttpMethod } from "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
- yarn
- npm
pnpm test
yarn test
npm test
If the documentation is not generated correctly, check the Integration with Test Runner guide.
4. Generate Reliable Documentation
When you run your tests, itdoc automatically generates an OpenAPI document in your project’s output/ directory. The following files will be created:
output/oas.json
: OpenAPI Specification (JSON)output/api.md
: Markdown version of the API docsoutput/redoc.html
: HTML documentation inredocly
style
These files are generated based on the API documentation defined in your test code, ensuring they are always accurate and reliable.
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.
{
// ... 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.