Documenting a Spring REST API Using Smart-doc
Tags: springboot, restapi, java
Published: 2024-06-22 16:10:19

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](https://smart-doc-group.github.io/#/README)

## 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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hde2m3v7lqaji04m38r5.png)

**Step 2: Add Smart-doc Into the Project**

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

```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 

```java
@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.

```java
/**
 * 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.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/icy2xhvjjr7jw0u0vt2c.png)


Of course, you can also use the Maven command to generate:
```shell
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.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7629l1zo696uy94xzqb6.png)

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.