Spring Data REST API integrates Springfox, Swagger

Original: documenting a Spring Data REST API with Springfox and Swagger

With spring date REST, you can quickly create rest APIs for spring date repositories, and provide crud and more functionality. However, with the rigorous API development success, you also want to have the latest API documentation automatically generated.

Code Example

This article comes with work sample code GitHub

Swagger provides a specification for documenting the rest API. Using Springfox, we have a tool that can be used as a bridge between the spring application and the swagger to create a swagger document for some spring beans and notes.

Springfox recently added a feature to create swagger documents for the spring Data REST API. This feature is still hatching, but I'm still playing a bit to assess whether it can be used in real projects. Because if so, the combination of Spring Data rest and Springfox will allow you to quickly develop a well-documented rest API.

Please note that, as of now (version 2.7.0), the Springfox integration for spring Data Rest is still in the incubation phase, and there are some serious errors and missing features (see here and here, for example). Therefore, the following description and code examples are based on the current 2.7.1-snapshot version, which can be greatly improved.

Enable Springfox in the Spring boot/spring Data Rest Application

To enable Springfox to create a swagger document for our spring Data REST API, you must perform the following steps.

Add Springfox Dependency

Add the following dependencies to your application (Gradle):

compile(‘io.springfox:springfox-swagger2:2.7.0‘)compile(‘io.springfox:springfox-data-rest:2.7.0‘)compile(‘io.springfox:springfox-swagger-ui:2.7.0‘)

• springfox-swagger2Contains the core functionality of Springfox, which allows the creation of API documentation using swagger 2.
• springfox-data-restContains integration for automating the creation of swagger documents for the Spring Data rest repository.
• springfox-swagger-uiContains the swagger UI, which http：// localhost：8080 / swagger-ui.html displays the swagger document in

Configure Application

Configure the Spring Boot application as follows:

@SpringBootApplication@EnableSwagger2@Import(SpringDataRestConfiguration.class)public class DemoApplication {    public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }

• @EnableSwagger2Annotations Enable swagger 2 support by registering certain beans in the context of the spring application.
• @ImportNote importing additional classes into the context of the spring application requires that the swagger document be created automatically from the Spring Data rest repository.

Creating a docket bean

You can choose to create a spring bean of the docket type. This will be picked up by Springfox to configure some swagger document output.

@Configurationpublic class SpringfoxConfiguration { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .tags(...) .apiInfo(...) ... } }

Spring Data repositories Add annotations

Optionally, you can use @api, @ApiOperation, and @apiparam annotations to annotate the spring data repository that is exposed by spring data rest. More details below.

Output

Finally, by accessing the browser http：// localhost：8080 / swagger-ui.html , you should be able to view the swagger documentation for the spring Data REST API. The result should be as shown.

Custom output

The numbers in the show some of the things that can be customized in the generated API documentation. The following sections describe some of the customizations I think are important. You can customize more than what I found, so feel free to add a comment if you find something I missed!

Common API Information

Information like title, description, license, etc. can be configured by creating a Docket bean, such as the code snippet above, and using its setter to change the desired settings.

Repository description

You can change the description of the repository by creating a tag that has exactly the same name as the default API name ("address entity" in the example), provide a description to the Docket tag in the object, and use the tag library to @Api connect to the tag library with annotations. So far, I can't find a way to modify the repository name.

@ConfigurationPublicClassspringfoxconfiguration {@BeanPublic DocketDocket() { return new Docket (documentationtype.swagger_2). tags ("Address Entity",  "Repository for Address Entities")); }}@Api (tags = "Address Entity")@RepositoryRestResource (Path = "addresses") Public Interface addressrepository extends crudrepository<Address, long> { //methods omitted}                  

Method description

The description of a single API operation can be @ApiOperation modified by annotations, as follows:

public interface AddressRepository extends PagingAndSortingRepository<Address, Long> {    @ApiOperation("find all Addresses that are associated with a given Customer")  Page<Address> findByCustomerId(@Param("customerId") Long customerId, Pageable pageable);  }

Input parameters

The name and description of the input parameter can be @ApiParam configured using annotations. Note that starting with Springfox 2.7.1, the parameter names are also read from the comments provided by spring data @Param .

public interface AddressRepository extends PagingAndSortingRepository<Address, Long> {    Page<Address> findByCustomerId(@Param("customerId") @ApiParam(value="ID of the customer") Long customerId, Pageable pageable);}

Response

You can use @ApiResponses and @ApiResponse annotate to adjust the different response states and their effective payload:

public interface AddressRepository extends PagingAndSortingRepository<Address, Long> {  @Override  @ApiResponses({@ApiResponse(code=201, message="Created", response=Address.class)})  Address save(Address address); }

Conclusion

Spring Data Rest allows you to produce fast results when you create a database-driven rest API. Springfox allows you to quickly generate automated documentation for the API. However, the API documentation generated by Springfox does not match the actual API in each detail. Some manual tweaks and annotations are necessary, as described in the customizing section above.

One such example is that the JSON for the sample request and response is not rendered correctly in each case because spring Data rest uses the HAL format, and Springfox is used only in a few cases. By working manually, the API documentation is difficult to keep up to date with every detail.

My conclusion is that the combination of Spring Data rest and Springfox is a good starting point for quickly generating a rest API, and its documentation is good enough for most use cases, especially when the API is developed and used in a set of closed developers. For the public API, the details are more important, so keeping swagger annotations and Springfox configurations up to date can be frustrating for every detail.

Spring Data REST API integrates Springfox, Swagger