Integrating smart-doc with SpringBoot: A Comprehensive Guide

Swagger vs smart-doc

Swagger requires invasive annotations and does not support parameter grouping out of the box, whereas smart-doc generates documentation by analyzing source code, needing only standard Java comments and producing Markdown or static HTML.

Advantages of smart-doc

Zero annotations, zero learning cost; just write standard Java comments.

Automatic inference of interface definitions and return structures.

Supports Spring MVC, Spring Boot, Spring WebFlux controllers.

Handles asynchronous return types such as Callable, Future, CompletableFuture.

Supports JSR‑303 validation and parameter groups.

Can generate mock values for common fields.

SpringBoot Integration

smart-doc can generate documentation via Maven plugin, Gradle plugin, or unit tests (the article uses the Maven plugin).

<!-- Add smart-doc plugin -->
<plugin>
  <groupId>com.github.shalousun</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>2.2.7</version>
  <configuration>
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <projectName>Smart-Doc First Experience</projectName>
  </configuration>
</plugin>

The key is to specify the configFile as smart-doc.json .

Create smart-doc.json with at least the output path: { "outPath": "src/main/resources/static/doc" }

Run the Maven command to generate HTML documentation: // generate HTML mvn -Dfile.encoding=UTF-8 smart-doc:html

Open http://localhost:8080/doc/api.html to view the generated API page.

Feature Enhancements

1. Enable Debugging

Add the following fields to the configuration to create an interactive debug page:

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName": "index.html",
  "projectName": "Intro to smart-doc"
}

After enabling createDebugPage , the debug page is available at http://localhost:8080/doc/index.html . If you open it directly from the IDE, you may encounter CORS issues, which can be solved by adding a global CORS filter:

@Configuration
public class WebMvcAutoConfig implements WebMvcConfigurer {

    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        config.addAllowedOrigin("*");
        config.addAllowedHeader("*");
        config.addAllowedMethod("*");
        source.registerCorsConfiguration("/**", config);
        return new CorsFilter(source);
    }
}

2. Common Response Body

To document a unified response wrapper (e.g., ResultData ), add the following to smart-doc.json :

{
  "responseBodyAdvice": {
    "className": "com.jianzh5.blog.base.ResultData"
  }
}

3. Custom Request Headers

Define headers such as a token that appear only on specific endpoints:

"requestHeaders": [
  {
    "name": "token",
    "type": "string",
    "desc": "Custom request header - token",
    "value": "123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns": "/smart/add,/smart/edit"
  }
]

4. Parameter Grouping

smart-doc fully supports parameter groups, allowing different required fields for create and edit operations, as shown in the generated documentation screenshots.

5. IDEA Tag Configuration

Custom tags (e.g., mock tags) need to be added to IDEA settings to enable auto‑completion.

6. Full Configuration Example

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName": "index.html",
  "projectName": "Intro to smart-doc",
  "packageFilters": "com.jianzh5.blog.smartdoc.*",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.jianzh5.blog.base.ReturnCode",
    "codeField": "code",
    "descField": "message"
  }],
  "responseBodyAdvice": {
    "className": "com.jianzh5.blog.base.ResultData"
  },
  "requestHeaders": [{
    "name": "token",
    "type": "string",
    "desc": "Custom request header - token",
    "value": "123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns": "/smart/add,/smart/edit"
  }]
}

Conclusion

smart-doc is straightforward to use; as long as you write standard Java comments, it can generate detailed API documentation, enforce comment standards across the team, and provide features such as debugging, unified response bodies, custom headers, and parameter grouping.