Generating up-to-date, accurate API documentation is essential for any service-oriented architecture, and Smart-Doc offers a lightweight, low-intrusion solution for Java projects. Smart-Doc analyses our Java source code and Javadoc comments to produce documentation in multiple formats (HTML, Markdown, OpenAPI, Postman, etc.). This article explains how to set up Smart-Doc with Maven and how to use Smart-Doc to generate documentation for a Spring Boot REST API.
1. Add the Maven Plugin
To use Smart-Doc, you need to add the smart-doc-maven-plugin to your pom.xml.
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>3.1.2</version> <!-- use latest version available -->
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.description}</projectName>
</configuration>
</plugin>
The plugin is defined with groupId=com.ly.smart-doc, artifactId=smart-doc-maven-plugin, and the latest stable version (3.1.2 in this example), while the <configuration> section specifies the JSON config file and optional project name. This setup ensures that executing mvn smart-doc: command automatically triggers Smart Doc to scan the source code and generate documentation accordingly.
2. Create Configuration File (smart-doc.json)
Smart-Doc uses a configuration file (usually smart-doc.json in src/main/resources) to control its output directory, server URL, and other options. Below is a sample configuration file.
{
"outPath": "./src/main/resources/static/doc",
"serverUrl": "http://localhost:8080"
}
The "outPath" defines where the generated documentation files are stored, here in static/doc within the resources folder for direct serving, and "serverUrl" specifies the base API URL used to construct full request endpoints in the generated output.
3. Sample REST Controller with Javadoc
Smart-Doc analyses Javadoc comments on our controllers, models and methods rather than requiring heavy annotation overhead. Below is a sample controller in a Spring Boot application.
/**
* REST controller for managing books in the catalog.
*/
@RestController
@RequestMapping("/api/v1/books")
public class BookController {
private final BookRepository bookRepository;
public BookController(BookRepository bookRepository) {
this.bookRepository = bookRepository;
}
/**
* Adds a new book to the catalog.
*
* @param book the book to be added
* @return the saved book
*/
@PostMapping
public ResponseEntity<Book> addBook(@RequestBody Book book) {
Book savedBook = bookRepository.save(book);
return ResponseEntity.ok(savedBook);
}
/**
* Retrieves all books from the catalog.
*
* @return a list of all books
*/
@GetMapping
public ResponseEntity<List<Book>> getAllBooks() {
List<Book> books = bookRepository.findAll();
return ResponseEntity.ok(books);
}
/**
* Retrieves a book by its ID.
*
* @param id the ID of the book
* @return the matching book, or 404 if not found
*/
@GetMapping("/{id}")
public ResponseEntity<Book> getBookById(@PathVariable Long id) {
return bookRepository.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}
}
The BookController provides REST endpoints for adding and retrieving books. Each method (addBook, getBookById, getAllBooks) is documented with Javadoc comments describing its purpose, parameters, and return values, which Smart Doc automatically parses and includes in the generated documentation. This eliminates the need for additional custom annotations, ensuring that the documentation remains closely aligned with the source code and simplifying maintenance by keeping it consistently up to date.
Book.java
/**
* Represents a book in the library catalog.
*/
public class Book {
/**
* The unique identifier of the book.
*/
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
/**
* The title of the book.
*/
private String title;
/**
* The author of the book.
*/
private String author;
/**
* The year the book was published.
*/
private int publicationYear;
/**
* The International Standard Book Number (ISBN).
*/
private String isbn;
// constructors, getters and setters
}
This class defines a simple JPA entity representing books in a library system. Each field and method is documented with Javadoc comments, which Smart Doc uses to generate descriptive API documentation.
4. Generate the Documentation
Once we have the plugin configured and our code annotated with Javadoc, we can generate the documentation via Maven. We can run multiple goals (HTML, Markdown, OpenAPI, Postman, etc.).
Example command:
mvn smart-doc:html
The goal smart-doc:html will produce HTML documentation in the path specified by outPath in our config file. When the documentation generation completes, the resulting HTML files, such as api.html, can be found in the src/main/resources/static/doc/ directory. Opening api.html in a browser displays the Smart Doc–generated documentation, presenting controllers, operations, parameters, responses, and model definitions in a clear, structured layout for easy review.
Smart-Doc not only generates static HTML or Markdown documentation but also supports producing machine-readable formats such as Postman collections and OpenAPI specifications. Smart Doc can generate a Postman collection that mirrors our REST endpoints with request URLs, methods, and sample parameters. This enables quick API testing directly from Postman without manually defining endpoints. We can create the Postman collection by running the following command:
mvn smart-doc:postman
This command scans the same project structure used for HTML generation and outputs a file named postman.json into the directory specified by the "outPath" property in our smart-doc.json configuration, for example:
src/main/resources/static/doc/postman.json
When the goal smart-doc:postman is executed, Smart-Doc converts the API definitions extracted from our controllers and Javadoc comments into a Postman-compatible JSON structure. Each REST endpoint becomes a request entry inside the collection, automatically including HTTP methods, URLs, parameters, and example request bodies.
We can then import this JSON file into Postman. Once imported, all our API endpoints appear organised, allowing us to execute requests directly against our running service and verify responses.
In addition to Postman, Smart-Doc supports generating OpenAPI 3.0 specifications. To generate an OpenAPI specification file, run the following Maven goal:
mvn smart-doc:openapi
The command produces a file named openapi.json inside the output path defined in our Smart Doc configuration. Example generated file path is:
src/main/resources/static/doc/openapi.json
The smart-doc:openapi goal generates the API specification in compliance with the OpenAPI 3.0 standard, producing a structured and interoperable schema that can be integrated with API gateways and visualisation tools. This standardised output ensures a consistent, machine-readable representation of the service’s endpoints, parameters, and responses. Once generated, the OpenAPI file can then be rendered interactively through Swagger UI for exploration and testing.
5. Conclusion
In this article, we explored the process of generating Java API documentation using Smart-Doc. We demonstrated how to configure Smart-Doc with Maven, define a JSON configuration file, and document a Spring Boot REST API using standard Javadoc comments without additional annotations.
6. Download the Source Code
This article explored Java API documentation using Smart Doc.
You can download the full source code of this example here: java api smart doc
