Smart-doc Deep Dive: Generate Java API Docs Without a Single Annotation

I’ll be honest — when I first came across Smart-doc, I was skeptical. A Java API documentation generator that claims “zero annotation intrusion”? In this space, Swagger is basically the industry standard, and Swagger is all about those @ApiOperation and @ApiParam annotations. Without annotations, how would it even know what your endpoints do?

So I spent an afternoon digging into it. And I have to say: Smart-doc actually delivers.

Project Background: Why Smart-doc Exists

Smart-doc comes from the Tongcheng Travel open-source team. It has 1,592 stars on GitHub — not exactly viral, but the community is reasonably active. The core idea is simple: generate documentation by analyzing your source code, without requiring any extra annotations.

The motivation is easy to understand if you’ve ever used Swagger. You probably know the pain:

• Every endpoint needs a pile of annotations, making your code bloated
• Annotations drift out of sync with the actual code, so docs become lies
• New team members need to learn Swagger’s annotation conventions
• Some projects (especially older ones) simply don’t want Swagger dependencies

The creators of Smart-doc clearly went through this themselves, so they took a different approach. Java code already has Javadoc comments. Interface definitions already contain parameter types, return values, and URL paths. Why add more annotations when you can just parse what’s already there?

Sounds simple, but it’s not. Java’s type erasure, nested objects, inheritance hierarchies, third-party dependencies — Smart-doc handles all of that. The source analysis engine is genuinely impressive.

(By the way, the original TongchengOpenSource/smart-doc repo was archived in December 2025. Active development has moved to smart-doc-group/smart-doc, with the latest version being 3.1.2.)

Core Features Deep Dive

1. Truly Zero Annotation Intrusion

This is Smart-doc’s biggest selling point, and it’s the one I wanted to verify most.

After testing it, I can confirm it works. You just write normal Javadoc comments:

/**
 * Get user information
 * @param userId User ID
 * @return User details
 */
@GetMapping("/user/{userId}")
public User getUser(@PathVariable Long userId) {
    return userService.getById(userId);
}

No @ApiOperation, no @ApiParam. Smart-doc extracts everything from the method signature and Javadoc. The generated docs include endpoint names, parameter descriptions, response structures, and even field comments pulled from your entity classes.

I was genuinely surprised here. I’ve tried other tools that claimed “zero intrusion” before, and they either had limited functionality or still required some config files. Smart-doc actually works out of the box.

2. Automatic Response Structure Derivation

Smart-doc’s response structure derivation is stronger than I expected. If your endpoint returns Result<User>, it not only recognizes the outer Result wrapper but also recursively parses every field in the User object — field types, whether they’re required, and field comments.

It even supports async interfaces: Callable, Future, and CompletableFuture are all handled correctly. For projects heavy on async programming, that’s genuinely useful.

3. Multiple Output Formats

Smart-doc supports a surprisingly wide range of output formats:

• HTML5: Clean static documentation pages with built-in search
• Markdown: Perfect for GitHub or documentation sites
• Word: For product managers or clients (though let’s be real, developers hate Word)
• OpenAPI 3.0: Can be consumed by Swagger UI
• Postman Collection: Import directly into Postman for API testing
• JMeter scripts: Saves time when you need to run load tests

I personally use the HTML and Postman exports most often. HTML docs can be deployed to an internal server, and Postman files go straight to frontend colleagues. Everyone wins.

4. Built-in Debug Page

Starting from version 2.0.1, Smart-doc can generate a debug.html page that works similarly to Swagger UI — you can test endpoints directly from the browser. The page is built with vanilla JavaScript, no frontend frameworks, so it loads fast.

One complaint though: this debug page needs CORS configuration to work properly. If you open the HTML file directly in your IDE, requests will fail with CORS errors. You need to add CORS config in Spring Boot, or serve the docs from a server. The docs mention this, but I still tripped over it the first time.

5. Torna Integration (Enterprise Document Management)

If you’re in an enterprise environment, the Smart-doc + Torna combo is worth considering. Torna is an open-source API documentation management platform. Smart-doc can push generated docs to Torna automatically, enabling version management and team collaboration.

The configuration is straightforward — just add a few lines to smart-doc.json:

{
  "appToken": "your-token",
  "openUrl": "http://torna-server/api",
  "replace": true,
  "debugEnvName": "Test Environment",
  "debugEnvUrl": "http://127.0.0.1:8080"
}

Then run mvn smart-doc:torna-rest to push. For teams maintaining large API suites, this workflow saves a lot of manual work.

Real-World Use Cases

Use Case 1: Documenting Legacy Projects

This is where Smart-doc shines brightest, in my opinion. Many legacy projects never had proper API docs, and catching up feels overwhelming. With Smart-doc, as long as your code has Javadoc comments (even poorly written ones), you can generate a decent starting point automatically. It won’t replace hand-written docs completely, but it’s a solid foundation.

Use Case 2: Projects That Avoid Extra Dependencies

Some projects are sensitive about dependencies — SDKs, base frameworks, that sort of thing. Adding Swagger increases the dependency chain unnecessarily. Smart-doc is a build-time tool only; it never makes it into your production artifact. That’s a clear advantage.

Use Case 3: Multi-Module Projects

Smart-doc supports loading source code from external dependencies, including sources JARs. For multi-module projects or projects that depend on internal shared libraries, this is handy. You can generate unified API docs for the entire system from a single module.

Quick Start Guide

Smart-doc works as both a Maven and Gradle plugin. Here’s the Maven setup:

Step 1: Add the plugin to your pom.xml:

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <configFile>./src/main/resources/smart-doc.json</configFile>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Step 2: Create smart-doc.json in your resources directory:

{
    "outPath": "./src/main/resources/static/doc",
    "serverUrl": "http://127.0.0.1:8080",
    "createDebugPage": true
}

Step 3: Generate docs:

mvn -Dfile.encoding=UTF-8 smart-doc:html

The generated docs will be in static/doc/. Start your Spring Boot app and visit http://localhost:8080/doc/index.html.

Want a different format? Swap html for markdown, openapi, postman, or torna-rest.

Pros and Cons

Pros

• Zero annotation intrusion: This is real, not marketing speak. No Smart-doc annotations needed in your code.
• Low learning curve: If you already write Javadoc, you barely need to learn anything new.
• Multiple output formats: HTML, Markdown, Postman, OpenAPI, JMeter, Word — solid coverage.
• Build-time only: No runtime dependencies, no performance impact.
• Strong source analysis: Handles generics, nested objects, and async interfaces correctly.

Cons (Let Me Complain Here)

• Doc quality depends on Javadoc: If your code comments are terrible, your generated docs will be terrible. Smart-doc won’t magically create descriptions — it can only parse what you already wrote. Some teams barely write comments, so the output ends up looking pretty bare.
• Less flexible than Swagger: Swagger annotations let you control lots of details — example values, hidden fields, custom response codes. Smart-doc has config options too, but they’re not as fine-grained as annotation-driven approaches.
• Debug page is basic: Compared to Swagger UI, Smart-doc’s debug page is pretty bare-bones. The UI isn’t as polished. It works for simple testing, but complex scenarios (file uploads, auth header management) aren’t as smooth.
• Smaller community: 1,592 stars vs Swagger’s 20k+. When you run into issues, there aren’t many Stack Overflow answers. You mostly rely on GitHub Issues and the official docs.
• Original repo archived: The TongchengOpenSource/smart-doc repo was archived, which gives off a “project abandoned” vibe. Development continues under smart-doc-group, but the transition might confuse some users.

Comparison with Alternatives

Feature	Smart-doc	Swagger (SpringDoc)
Annotation intrusion	Zero	Requires many annotations
Learning curve	Low (Javadoc only)	Medium (learn Swagger annotations)
Output formats	HTML/Markdown/Postman/OpenAPI/Word/JMeter	HTML/OpenAPI/Postman
Runtime dependencies	None	Yes (swagger-ui, etc.)
Flexibility	Medium (config file)	High (fine-grained annotations)
Community size	Small (1.5k stars)	Large (20k+ stars)
Debug page	Basic	Full-featured

Which should you choose?

• Pick Smart-doc if you hate writing annotations, your project is sensitive to dependencies, or you need to document a legacy codebase.
• Pick SpringDoc if you need fine-grained control over docs, your team already knows Swagger, or you want a polished online debugging experience.

These tools aren’t mutually exclusive, by the way. Smart-doc can generate OpenAPI specs, and you can display them with Swagger UI. Best of both worlds.

Target Audience and Final Thoughts

Smart-doc is best for:

1. Developers who hate annotation bloat — if @ApiOperation makes you cringe, Smart-doc will feel refreshing.
2. Engineers maintaining legacy projects — code has Javadoc but lacks proper API docs.
3. Teams sensitive to dependencies — SDK teams, framework teams who don’t want Swagger in production.
4. Small-to-medium teams that need docs fast — don’t need heavy customization, just something that works.

To wrap up, Smart-doc is a “good enough and hassle-free” tool. It won’t give you the most powerful or flexible documentation generation, but it genuinely delivers on “zero intrusion” and “low learning curve.” In this niche, that’s already valuable.

If you’re already using Swagger, you don’t necessarily need to switch. But if you’re starting a new project or currently suffering through Swagger annotations, Smart-doc is absolutely worth a try.

At the very least, it restored my belief in one thing: good tools should make your life easier, not add to your burden.