In case you are creating a RESTful API with Spring Boot, you wish to make it as straightforward as doable for different builders to know and use your API. Documentation is important as a result of it gives a reference for future updates and helps different builders combine along with your API. For a very long time, the best way to doc REST APIs was to make use of Swagger, an open-source software program framework that allows builders to design, construct, doc, and eat RESTful Net providers. In 2018, to deal with the problems of code invasiveness and dependency related to conventional API documentation instruments like Swagger, we developed smart-doc and open-sourced it to the group.
On this article, we are going to discover how you can use Sensible-doc to generate documentation for a Spring Boot REST API.
What Is Sensible-doc?
Sensible-doc is an interface documentation era software for Java tasks. It primarily analyzes and extracts feedback from Java supply code to supply API documentation. Sensible-doc scans customary Java feedback within the code, eliminating the necessity for specialised annotations like these utilized in Swagger, thus sustaining the simplicity and non-invasiveness of the code. It helps a number of codecs for doc output, together with Markdown, HTML5, Postman Assortment, OpenAPI 3.0, and so forth. This flexibility permits builders to decide on the suitable documentation format based mostly on their wants. Moreover, Sensible-doc can scan code to generate JMeter efficiency testing scripts.
For extra options, please seek advice from the official documentation.
Steps To Use Sensible-doc for Documenting APIs
Step 1: Maven Mission
- Create a Maven challenge with the newest model of Spring Boot
- Add the Net dependencies to the challenge
Step 2: Add Sensible-doc Into the Mission
- Add
smart-doc-maven-pluginto the challenge’spom.xml
com.ly.smart-doc
smart-doc-maven-plugin
[latest version]
./src/essential/assets/smart-doc.json
${challenge.description}
- Create the
smart-doc.jsonfile within the assets listing of the module the place the challenge startup class is situated.
{
"outPath": "/path/to/userdir"
}Step 3: Create a Relaxation Controller
Now let’s create a controller class that may deal with HTTP requests and return responses.
- Create a controller class that might be despatched as a JSON response.
public class Person {
/**
* person id
*
*/
non-public lengthy id;
/**
* first title
*/
non-public String firstName;
/**
* final title
*/
non-public String lastName;
/**
* e-mail deal with
*/
non-public String e-mail;
public lengthy getId() {
return id;
}
public void setId(lengthy 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 e-mail;
}
public void setEmail(String e-mail) {
this.e-mail = e-mail;
}
}- Now create a service class
@Repository
public class UserRepository {
non-public static last Map customers = new ConcurrentHashMap();
static {
Person person = new Person();
person.setId(1);
person.setEmail("123@gmail.com");
person.setFirstName("Tom");
person.setLastName("King");
customers.put(1L,person);
}
public Non-compulsory findById(lengthy id) {
return Non-compulsory.ofNullable(customers.get(id));
}
public void add(Person e-book) {
customers.put(e-book.getId(), e-book);
}
public Record getUsers() {
return customers.values().stream().gather(Collectors.toList());
}
public boolean delete(Person person) {
return customers.take away(person.getId(),person);
}
} - Create the RestController Class.
/**
* The kind Person controller.
*
* @writer yu 2020/12/27.
*/
@RestController
@RequestMapping("/api/v1")
public class UserController {
@Useful resource
non-public UserRepository userRepository;
/**
* Create person.
*
* @param person the person
* @return the person
*/
@PostMapping("/users")
public ResponseResult createUser(@Legitimate @RequestBody Person person) {
userRepository.add(person);
return ResponseResult.okay(person);
}
/**
* Get all customers record.
*
* @return the record
*/
@GetMapping("/users")
public ResponseResult> getAllUsers() {
return ResponseResult.okay().setResultData(userRepository.getUsers());
}
/**
* Will get customers by id.
*
* @param userId the person id|1
* @return the customers by id
*/
@GetMapping("/users/{id}")
public ResponseResult getUsersById(@PathVariable(worth = "id") Lengthy userId) {
Person person = userRepository.findById(userId).
orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
return ResponseResult.okay().setResultData(person);
}
/**
* Replace person response entity.
*
* @param userId the person id|1
* @param userDetails the person particulars
* @return the response entity
*/
@PutMapping("/users/{id}")
public ResponseResult updateUser(@PathVariable(worth = "id") Lengthy userId, @Legitimate @RequestBody Person userDetails) {
Person person = userRepository.findById(userId).
orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
person.setEmail(userDetails.getEmail());
person.setLastName(userDetails.getLastName());
person.setFirstName(userDetails.getFirstName());
userRepository.add(person);
return ResponseResult.okay().setResultData(person);
}
/**
* Delete person.
*
* @param userId the person id|1
* @return the map
*/
@DeleteMapping("/user/{id}")
public ResponseResult deleteUser(@PathVariable(worth = "id") Lengthy userId) {
Person person = userRepository.findById(userId).
orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
return ResponseResult.okay().setResultData(userRepository.delete(person));
}
}
Step 4: Generate a Doc
You need to use the Sensible-doc plugin in IntelliJ IDEA to generate the specified documentation, corresponding to OpenAPI, Markdown, and so forth.
After all, you can too use the Maven command to generate:
mvn smart-doc:html
// Generate doc output to Markdown
mvn smart-doc:markdown
// Generate doc output to Adoc
mvn smart-doc:adoc
// Generate Postman.
mvn smart-doc:postman
// Generate OpenAPI 3.0+
mvn smart-doc:openapiStep 4: Import to Postman
Right here we use Sensible-doc to generate a Postman.json, then import it into Postman to see the impact.
Since smart-doc helps producing documentation in a number of codecs, you’ll be able to select to generate OpenAPI after which show it utilizing Swagger UI or import it into some skilled API documentation techniques.
Conclusion
From the earlier examples, it may be seen that Sensible-doc generates documentation by scanning customary Java feedback within the code, with out the necessity for specialised annotations like Swagger, thus sustaining the simplicity and non-invasiveness of the code, and likewise not affecting the dimensions of the service Jar bundle. It helps a number of codecs for doc output, together with Markdown, HTML5, Postman Assortment,OpenAPI 3.0, and so forth. This flexibility permits builders to decide on the suitable doc format for output based mostly on their wants. The Maven or Gradle plugins supplied by smart-doc additionally facilitate customers in integrating doc era in Devops pipelines.
At present, Swagger additionally has its benefits, corresponding to extra highly effective UI options, and higher assist for Springboot Webflux.