Documenting a Spring REST API Using Smart-doc

If you are developing a RESTful API with Spring Boot, you want to make it as easy as possible for other developers to understand and use your API. Documentation is essential because it provides a reference for future updates and helps other developers integrate with your API. For a long time, the way to document REST APIs was to use Swagger, an open-source software framework that enables developers to design, build, document, and consume RESTful Web services. In 2018, to address the issues of code invasiveness and dependency associated with traditional API documentation tools like Swagger, we developed smart-doc and open-sourced it to the community.
In this article, we will explore how to use Smart-doc to generate documentation for a Spring Boot REST API.

What is Smart-doc?

Smart-doc is an interface documentation generation tool for Java projects. It primarily analyzes and extracts comments from Java source code to produce API documentation. Smart-doc scans standard Java comments in the code, eliminating the need for specialized annotations like those used in Swagger, thus maintaining the simplicity and non-invasiveness of the code. It supports multiple formats for document output, including Markdown, HTML5, Postman Collection, OpenAPI 3.0, etc. This flexibility allows developers to choose the appropriate documentation format based on their needs. Additionally, Smart-doc can scan code to generate JMeter performance testing scripts.

For more features, please refer to the official documentation

Steps to use Smart-doc for documenting APIs

Step 1: Maven Project

Create a Maven project with the latest version of Spring Boot
Add the Web dependencies to the project

Step 2: Add Smart-doc Into the Project

Add smart-doc-maven-plugin to the project's pom.xml



<plugin>
     <groupId>com.ly.smart-doc</groupId>
     <artifactId>smart-doc-maven-plugin</artifactId>
     <version>[latest version]</version>
     <configuration>
         <configFile>./src/main/resources/smart-doc.json</configFile>
         <projectName>${project.description}</projectName>
     </configuration>
</plugin>

Create the smart-doc.json file in the resources directory of the module where the project startup class is located. ```json

{
"outPath": "/path/to/userdir"
}


**Step 3: Create a Rest Controller**

Now let's create a controller class that will handle HTTP requests and return responses.

- Create a controller class that will be sent as a JSON response.

```java


public class User {

    /**
     * user id
     * 
     */
    private long id;

    /**
     * first name
     */
    private String firstName;

    /**
     * last name
     */
    private String lastName;

    /**
     * email address
     */
    private String email;


    public long getId() {
        return id;
    }

    public void setId(long id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

Now create a service class



@Repository
public class UserRepository {

    private static final Map<Long, User> users = new ConcurrentHashMap<>();

    static {
        User user = new User();
        user.setId(1);
        user.setEmail("123@gmail.com");
        user.setFirstName("Tom");
        user.setLastName("King");
        users.put(1L,user);
    }

    public Optional<User> findById(long id) {
        return Optional.ofNullable(users.get(id));
    }

    public void add(User book) {
        users.put(book.getId(), book);
    }

    public List<User> getUsers() {
        return users.values().stream().collect(Collectors.toList());
    }

    public boolean delete(User user) {
        return users.remove(user.getId(),user);
    }
}

Create the RestController Class.



/**
 * The type User controller.
 *
 * @author yu 2020/12/27.
 */
@RestController
@RequestMapping("/api/v1")
public class UserController {

    @Resource
    private UserRepository userRepository;

    /**
     * Create user.
     *
     * @param user the user
     * @return the user
     */
    @PostMapping("/users")
    public ResponseResult<User> createUser(@Valid @RequestBody User user) {
        userRepository.add(user);
        return ResponseResult.ok(user);
    }

    /**
     * Get all users list.
     *
     * @return the list
     */
    @GetMapping("/users")
    public ResponseResult<List<User>> getAllUsers() {
        return ResponseResult.ok().setResultData(userRepository.getUsers());
    }

    /**
     * Gets users by id.
     *
     * @param userId the user id|1
     * @return the users by id
     */
    @GetMapping("/users/{id}")
    public ResponseResult<User> getUsersById(@PathVariable(value = "id") Long userId) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        return ResponseResult.ok().setResultData(user);
    }


    /**
     * Update user response entity.
     *
     * @param userId      the user id|1
     * @param userDetails the user details
     * @return the response entity
     */
    @PutMapping("/users/{id}")
    public ResponseResult<User> updateUser(@PathVariable(value = "id") Long userId, @Valid @RequestBody User userDetails) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        user.setEmail(userDetails.getEmail());
        user.setLastName(userDetails.getLastName());
        user.setFirstName(userDetails.getFirstName());
        userRepository.add(user);
        return ResponseResult.ok().setResultData(user);
    }

    /**
     * Delete user.
     *
     * @param userId the user id|1
     * @return the map
     */
    @DeleteMapping("/user/{id}")
    public ResponseResult<Boolean> deleteUser(@PathVariable(value = "id") Long userId) {
        User user = userRepository.findById(userId).
                orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
        return ResponseResult.ok().setResultData(userRepository.delete(user));
    }
}

Step 4: Generate document

You can use the Smart-doc plugin in IntelliJ IDEA to generate the desired documentation, such as OpenAPI, Markdown, etc.

Of course, you can also use the Maven command to generate:



mvn smart-doc:html
//  Generate document output to Markdown
mvn smart-doc:markdown
// Generate document output to Adoc
mvn smart-doc:adoc
// Generate Postman.
mvn smart-doc:postman
// Generate OpenAPI 3.0+
mvn smart-doc:openapi

Step 4: Import to Postman

Here we use Smart-doc to generate a Postman.json, then import it into Postman to see the effect.

Since smart-doc supports generating documentation in multiple formats, you can choose to generate OpenAPI and then display it using Swagger UI or import it into some professional API documentation systems.

Conclusion

From the previous examples, it can be seen that Smart-doc generates documentation by scanning standard Java comments in the code, without the need for specialized annotations like Swagger, thus maintaining the simplicity and non-invasiveness of the code, and also not affecting the size of the service Jar package. It supports multiple formats for document output, including Markdown, HTML5, Postman Collection,OpenAPI 3.0, etc. This flexibility allows developers to choose the appropriate document format for output based on their needs. The Maven or Gradle plugins provided by smart-doc also facilitate users in integrating document generation in Devops pipelines.

Currently, Swagger also has its advantages, such as more powerful UI features, and better support for Springboot Webflux.

Blog

Documenting a Spring REST API Using Smart-doc

Yu Sun

What is Smart-doc?

Steps to use Smart-doc for documenting APIs

Conclusion

Join Our Newsletter. No Spam, Only the good stuff.

Related