https://github.com/do-pa/itdoc
The Best Node.js Tool for Automatically Generating API Documentation from Test Code
https://github.com/do-pa/itdoc
api-documentation javascript nodejs openapi3 test-automation test-driven typescript
Last synced: 8 months ago
JSON representation
The Best Node.js Tool for Automatically Generating API Documentation from Test Code
- Host: GitHub
- URL: https://github.com/do-pa/itdoc
- Owner: do-pa
- License: apache-2.0
- Created: 2025-02-22T03:12:55.000Z (about 1 year ago)
- Default Branch: develop
- Last Pushed: 2025-08-20T05:21:34.000Z (9 months ago)
- Last Synced: 2025-08-20T07:21:17.603Z (9 months ago)
- Topics: api-documentation, javascript, nodejs, openapi3, test-automation, test-driven, typescript
- Language: TypeScript
- Homepage: https://itdoc.kr/
- Size: 10.2 MB
- Stars: 108
- Watchers: 2
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
itdoc
[](https://github.com/do-pa/itdoc/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/itdoc)
[](http://www.apache.org/licenses/LICENSE-2.0.html)
[](https://discord.gg/ZhXk7VSu5Z)
**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].
[swagger-jsdoc]: https://github.com/Surnet/swagger-jsdoc
[swagger-ui-express]: https://github.com/scottie1984/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](https://swagger.io/specification/), Markdown, and HTML
([Redoc-style](https://redocly.github.io/redoc/)).
- **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](https://itdoc.kr/docs/guides/configuration))
[//]: # "TODO : 나중에 CLI 문서 작성된다면, REAMDE에 추가할 것."
[OpenAPI Specification]: https://swagger.io/specification/
[Redoc-style]: https://redocly.github.io/redoc/
[HTML output]: http://redocly.com/demo/openapi/museum-api/operations/getmuseumhours
## Installation
```bash
npm install itdoc --save-dev
```
## Documentation
Full documentation for itdoc can be found on the [official website](https://itdoc.kr/).
> you can contribute to improving our documentation by submitting a PR to our
> [docs folder](https://github.com/do-pa/itdoc/tree/develop/itdoc-doc).
## Examples
We have several examples available in the [examples directory]. Here's a simple Express example to
help you get started.
```javascript
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"),
})
})
},
)
```
[examples directory]: https://github.com/do-pa/itdoc/tree/develop/examples
> - 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].
[Quick Start Guide]: https://itdoc.kr/docs/guides/quick-start
[NestJS guide]: https://itdoc.kr/docs/guides/framework-guide/#nestjs-example
[fastify guide]: https://itdoc.kr/docs/guides/framework-guide/#fastify-example
## Running Tests
Since `describeAPI()` and `itdoc()` integrate seamlessly with testing frameworks like
[Jest](https://jestjs.io/docs/getting-started) and [Mocha](https://mochajs.org/#getting-started),
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](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the terms of the [Apache 2.0 License](LICENSE.txt).