Generate Zero‑Annotation API Docs with smart‑doc for SpringBoot

Front‑backend interface debugging requires API documentation; while Swagger is commonly used, smart-doc offers many advantages and is recommended.

Talking about Swagger

When using Swagger we often rely on annotations such as

@Api

and

@ApiOperation

to generate API docs. Example code:

<code>&lt;!-- Example Swagger‑annotated controller method --&gt;
// ...
</code>

Swagger can be invasive, duplicating information in comments and annotations. smart-doc provides a zero‑annotation solution that generates documentation directly from code comments.

smart-doc Overview

smart-doc is an API documentation generator that requires only well‑written code comments to produce documentation and can also generate a Postman debug file for one‑click import.

Key advantages of smart-doc include:

Zero annotation intrusion

Automatic generation of Postman collection files

Support for custom tags and response wrappers

Generate API Documentation

First, add the smart-doc Maven plugin to the project. The plugin itself does not require additional dependencies, achieving true zero‑intrusion.

<code>&lt;plugin&gt;
    &lt;groupId&gt;com.github.shalousun&lt;/groupId&gt;
    &lt;artifactId&gt;smart-doc-maven-plugin&lt;/artifactId&gt;
    &lt;version&gt;2.2.8&lt;/version&gt;
    &lt;configuration&gt;
        &lt;!-- Path to smart‑doc configuration file --&gt;
        &lt;configFile&gt;./src/main/resources/smart-doc.json&lt;/configFile&gt;
        &lt;!-- Project name --&gt;
        &lt;projectName&gt;mall-tiny-smart-doc&lt;/projectName&gt;
    &lt;/configuration&gt;
&lt;/plugin&gt;
</code>

Next, create

smart-doc.json

under

src/main/resources

with the following settings (comments omitted for brevity):

<code>{
  "serverUrl": "http://localhost:8088",
  "outPath": "src/main/resources/static/doc",
  "isStrict": false,
  "allInOne": true,
  "createDebugPage": false,
  "packageFilters": "com.macro.mall.tiny.controller.*",
  "style": "xt256",
  "projectName": "mall-tiny-smart-doc",
  "showAuthor": false,
  "allInOneDocFileName": "index.html"
}
</code>

Run the Maven goal

smart-doc:html

from the IDEA Maven panel. The generated documentation appears under

static/doc

, including detailed request parameters and response results, accessible at

http://localhost:8088/doc/index.html

.

Entity classes need only field comments; smart-doc extracts them automatically. Example entity:

<code>public class PmsBrand implements Serializable {
    /** ID */
    private Long id;
    /** Name */
    private String name;
    /** First letter */
    private String firstLetter;
    // ... other fields and getters/setters omitted
}
</code>

Controller methods also require only comments. Example controller method:

<code>/**
 * Paginated brand list
 * @param pageNum page number
 * @param pageSize page size
 */
@RequestMapping(value = "/list", method = RequestMethod.GET)
@ResponseBody
@PreAuthorize("hasRole('ADMIN')")
public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
                                                    @RequestParam(value = "pageSize", defaultValue = "3") Integer pageSize) {
    List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
    return CommonResult.success(CommonPage.restPage(brandList));
}
</code>

smart-doc also supports custom annotation tags to enhance documentation:

@ignore

: exclude the field from the generated doc

@required

: mark a request parameter as mandatory

@since

: indicate the version when the field was added

To unify response structures, add the following to

smart-doc.json

:

<code>{
  "responseBodyAdvice": {
    "className": "com.macro.mall.tiny.common.api.CommonResult"
  }
}
</code>

Configure error‑code dictionaries:

<code>{
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.macro.mall.tiny.common.api.ResultCode",
    "codeField": "code",
    "descField": "message"
  }]
}
</code>

Define custom request headers (e.g.,

Authorization

) in

smart-doc.json

:

<code>{
  "requestHeaders": [{
    "name": "Authorization",
    "type": "string",
    "desc": "token request header value",
    "value": "token request header value",
    "required": false,
    "since": "-",
    "pathPatterns": "/brand/**",
    "excludePathPatterns": "/admin/login"
  }]
}
</code>

Using Postman to Test Interfaces

smart-doc’s built‑in interface testing is limited, so it provides a Postman JSON generator. Execute smart-doc:postman to create postman.json in static/doc , then import the file into Postman for full testing.

After importing, all generated interfaces appear in Postman, enabling convenient testing.

Conclusion

smart-doc is a practical API documentation tool with zero‑annotation intrusion. Although its native testing features are weak, the ability to generate Postman collections makes it highly convenient for developers.