The Ultimate Guide to API Documentation with Smart-Doc

Table of Contents#

1. What is Smart-Doc?
2. Why Choose Smart-Doc Over Alternatives?
3. Getting Started: Installation and Setup
   • Maven Setup
   • Gradle Setup
   • Creating the Configuration File (smart-doc.json)
4. Writing Effective Code Comments for Smart-Doc
   • Controller and Endpoint Documentation
   • Data Model Documentation (DTOs)
   • Common Javadoc Tags
5. Generating Documentation
   • Using the Maven Plugin
   • Using the Gradle Plugin
6. Output Formats and Integration
   • HTML Documentation
   • OpenAPI (Swagger) Specification
   • Postman Collection
7. Advanced Features and Best Practices
   • Grouping APIs
   • Error Code Documentation
   • Using @apiNote for Detailed Instructions
   • Validation Annotations Integration
8. Common Pitfalls and How to Avoid Them
9. Conclusion
10. References

What is Smart-Doc?#

Smart-Doc is an open-source Java library that parses source code comments (Javadoc) and annotations to generate API documentation without requiring you to embed specific annotations directly into your controller code (like @ApiOperation from Swagger). It works by analyzing your code structure during the build process.

Key Characteristics:

• Annotation-Free Controllers: Your controller classes remain clean, focused solely on request handling logic.
• Javadoc-Driven: It uses the existing, standard Javadoc syntax you are already familiar with.
• Multiple Output Formats: Generates HTML, Markdown, OpenAPI 3.0 (formerly Swagger), Postman collections, and more.
• Accurate and Always Updated: Since it's generated from the code, the documentation is always in sync with the actual implementation.

Why Choose Smart-Doc Over Alternatives?#

Getting Started: Installation and Setup#

Maven Setup#

Add the smart-doc-maven-plugin to your pom.xml inside the <build><plugins> section.

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.7.7</version> <!-- Check for the latest version -->
    <configuration>
        <!-- Point to your config file -->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!-- Optional: Specify the project name -->
        <projectName>My Awesome API</projectName>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>html</goal> <!-- Goal can be 'html', 'openapi', 'postman' etc. -->
            </goals>
        </execution>
    </executions>
</plugin>

Gradle Setup#

For Gradle, you need to apply the plugin in your build.gradle file.

First, add the plugin to your classpath in the plugins block (Gradle 2.1+):

plugins {
  id "com.ly.smart-doc" version "2.7.7"
}

Or, for older Gradle versions, use the buildscript block:

buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        mavenCentral()
    }
    dependencies {
        classpath 'com.ly.smart-doc:smart-doc-gradle-plugin:2.7.7'
    }
}
apply plugin: 'com.ly.smart-doc'

Then, configure the task:

smartdoc {
    configFile = file("src/main/resources/smart-doc.json")
}

Creating the Configuration File (smart-doc.json)#

This JSON file is the heart of Smart-Doc's configuration. Create it in src/main/resources/smart-doc.json.

{
  "serverUrl": "http://localhost:8080",
  "isStrict": false,
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "coverOld": true,
  "style": "xt256",
  "createDebugPage": true,
  "packageFilters": "com.example.api.controller.*",
  "projectName": "User Management API",
  "skipTransientField": false,
  "sortByTitle": false,
  "requestExample": true,
  "responseExample": true
}

Key Configuration Parameters:

• serverUrl: The base URL of your API.
• allInOne: Whether to output all documentation into a single file.
• outPath: The directory where the generated documentation will be saved.
• packageFilters: Restrict Smart-Doc to scan only specific packages (improves performance).
• requestExample / responseExample: Control whether to generate example request/response bodies.

Writing Effective Code Comments for Smart-Doc#

The quality of your documentation is directly proportional to the quality of your Javadoc comments.

Controller and Endpoint Documentation#

/**
 * REST Controller for managing users in the system.
 * Provides endpoints for CRUD operations on user entities.
 *
 * @author Jane Developer
 * @version 1.0
 */
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
 
    @Autowired
    private UserService userService;
 
    /**
     * Retrieves a user by their unique identifier.
     *
     * @param id the unique ID of the user to retrieve. Must be a positive integer.
     * @return the {@link UserResponse} object containing user details.
     * @throws UserNotFoundException if no user is found with the given ID.
     * @apiNote This endpoint is idempotent. Multiple identical calls will return the same result.
     */
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUserById(@PathVariable("id") @Min(1) Long id) {
        // ... implementation
    }
 
    /**
     * Creates a new user in the system.
     *
     * @param userRequest the {@link UserRequest} object containing the new user's data.
     * @return the {@link UserResponse} object of the newly created user.
     * @apiNote The user's email address must be unique. Passwords are hashed before storage.
     */
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@Valid @RequestBody UserRequest userRequest) {
        // ... implementation
    }
}

Data Model Documentation (DTOs)#

Document your Data Transfer Objects (DTOs) to describe the expected request and response structures.

/**
 * Represents the data required to create a new user.
 */
public class UserRequest {
 
    /**
     * The full name of the user.
     * Must be between 2 and 100 characters.
     */
    @NotBlank
    @Size(min = 2, max = 100)
    private String fullName;
 
    /**
     * The user's email address.
     * Must be a valid and unique email format.
     */
    @NotBlank
    @Email
    private String email;
 
    /**
     * The user's password.
     * Must contain at least one uppercase letter, one lowercase letter, one number, and be at least 8 characters long.
     */
    @NotBlank
    @Pattern(regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).{8,}$")
    private String password;
 
    // ... getters and setters
}
 
/**
 * Represents the data returned for a user.
 */
public class UserResponse {
 
    /**
     * The unique database identifier for the user.
     */
    private Long id;
 
    /**
     * The full name of the user.
     */
    private String fullName;
 
    /**
     * The user's email address.
     */
    private String email;
 
    /**
     * The timestamp when the user account was created.
     * Format: ISO-8601 (e.g., 2023-10-27T10:30:00Z)
     */
    private LocalDateTime createdAt;
 
    // ... getters and setters
}

Common Javadoc Tags#

• @param: Describes a method parameter.
• @return: Describes the return value.
• @throws / @exception: Describes the exceptions a method can throw.
• @apiNote: Provides additional implementation notes or important details for the API consumer. This is very useful for Smart-Doc.
• @deprecated: Marks an endpoint or parameter as deprecated.

Generating Documentation#

Using the Maven Plugin#

After setup, you can generate documentation using Maven commands.

• Generate HTML: mvn smart-doc:html
• Generate OpenAPI Spec: mvn smart-doc:openapi
• Generate Postman Collection: mvn smart-doc:postman

If you configured the execution phase as shown earlier, the documentation will be generated automatically every time you run mvn compile.

Using the Gradle Plugin#

Similarly, with Gradle:

• Generate HTML: gradle smartDocHtml
• Generate OpenAPI Spec: gradle smartDocOpenApi
• Generate Postman Collection: gradle smartDocPostman

Output Formats and Integration#

HTML Documentation#

Smart-Doc's HTML output is a fully self-contained, interactive documentation site. It includes:

• A sidebar for easy navigation between endpoints.
• Detailed descriptions of each endpoint, parameter, and response.
• Example request and response bodies.
• A "debug" page for testing endpoints directly from the browser (if createDebugPage is true).

OpenAPI (Swagger) Specification#

By generating an OpenAPI 3.0 specification file (openapi.json), you can integrate with the vast Swagger ecosystem.

• Use Swagger UI to host an interactive API console: mvn smart-doc:openapi and then feed the generated JSON to Swagger UI.
• Import the spec into API gateways like AWS API Gateway or Azure API Management.

Postman Collection#

Generating a Postman collection (postman.json) is incredibly valuable for testing and sharing.

• Import the JSON file directly into Postman.
• All your endpoints, headers, and example bodies will be pre-configured, saving testers and consumers significant time.

Advanced Features and Best Practices#

Grouping APIs#

You can organize your APIs into groups for better readability. Use the @group tag in your controller's Javadoc.

/**
 * User Management API
 * @group User Management - Core operations for system users.
 */
@RestController
@RequestMapping("/api/v1/users")
public class UserController { ... }
 
/**
 * Authentication API
 * @group Authentication - Endpoints for login, logout, and token management.
 */
@RestController
@RequestMapping("/api/v1/auth")
public class AuthController { ... }

Error Code Documentation#

Document common error codes per endpoint using the @apiNote tag.

/**
 * Retrieves a user by their unique identifier.
 *
 * @param id the unique ID of the user
 * @return the user details
 * @apiNote
 * <p>Common Error Codes:</p>
 * <ul>
 *   <li>404 - UserNotFoundException: If no user is found.</li>
 *   <li>400 - InvalidIdException: If the provided ID is not a positive number.</li>
 *   <li>500 - InternalServerError: For any unforeseen server issues.</li>
 * </ul>
 */

Using @apiNote for Detailed Instructions#

The @apiNote tag is your best friend for adding crucial, non-structural information.

/**
 * @apiNote
 * <h3>Authentication Required</h3>
 * This endpoint requires a valid JWT token in the `Authorization` header.
 * <p><b>Example Header:</b><br>
 * <code>Authorization: Bearer your.jwt.token.here</code></p>
 *
 * <h3>Rate Limiting</h3>
 * This endpoint is limited to 100 requests per hour per API key.
 */

Validation Annotations Integration#

Smart-Doc automatically picks up Bean Validation annotations (@NotNull, @Size, @Pattern, etc.) and includes them in the parameter documentation. This makes the generated documentation much more precise.

Common Pitfalls and How to Avoid Them#

1. Sparse Javadoc Comments: If your comments are just /** Gets the user. */, your documentation will be useless.

   • Solution: Adopt a culture of writing meaningful, descriptive Javadoc for all public controllers and DTOs.

2. Incorrect packageFilters: If your configuration scans the entire classpath, it can be slow and might pick up internal classes.

   • Solution: Always define a precise packageFilters value targeting your controller and model packages (e.g., "com.yourcompany.api.*").

3. Generic Type Parameters: Smart-Doc can sometimes struggle with highly complex, nested generic types.

   • Solution: Use concrete classes for request/response bodies where possible. If you must use generics like ResponseEntity<Page<UserResponse>>, ensure the inner types (like UserResponse) are well-documented.

4. Ignoring the Build: Forgetting to regenerate documentation after code changes.

   • Solution: Integrate the Smart-Doc goal into your default build lifecycle (e.g., the compile phase in Maven) or make it part of your CI/CD pipeline.

Conclusion#

Smart-Doc offers a powerful, elegant, and maintainable solution to the perennial problem of API documentation. By treating documentation as a natural byproduct of the development process—through thoughtful code comments—it ensures that your docs are always accurate and synchronized with your codebase.

The initial investment in writing good Javadoc pays enormous dividends in reduced support tickets, faster onboarding for new developers, and a more professional API offering. By following the practices outlined in this guide, you can leverage Smart-Doc to create comprehensive, high-quality API documentation that truly serves its purpose.

Start integrating Smart-Doc into your next project and experience the difference of having documentation that works for you, not against you.

References#

1. Smart-Doc Official Website & Documentation: https://smart-doc-group.github.io/
2. Smart-Doc GitHub Repository: https://github.com/smart-doc-group/smart-doc
3. Maven Central: smart-doc-maven-plugin: https://mvnrepository.com/artifact/com.ly.smart-doc/smart-doc-maven-plugin
4. OpenAPI Specification: https://swagger.io/specification/
5. Oracle's Guide to Writing Javadoc: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html