1. Overview

When creating a REST API, good documentation is instrumental.

Moreover, every change in the API should be simultaneously described in the reference documentation. Accomplishing this manually is a tedious exercise, so automation of the process was inevitable.

In this tutorial we will look at Swagger 2 for a Spring REST web service. For the purposes of this article, we will use the Springfox implementation of the Swagger 2 specification.

If you are not familiar with Swagger, you should visit its web page to learn more before continuing with this article.

2. Target Project

The creation of the REST service we will use in our examples is not within the scope of this article. If you already have a suitable project, use it. If not, the following links are a good place to start:

• Build a REST API with Spring 4 and Java Config article
• Building a RESTful Web Service.

3. Adding the Maven Dependency

As mentioned above, we will use the Springfox implementation of the Swagger specification. To add it to our Maven project, we need a dependency in the pom.xml file.

4. Integrating Swagger 2 into the Project

4.1. Java Configuration

Configuration of Swagger mainly centers around the Docket bean.

Swagger 2 is enabled through the @EnableSwagger2 annotation.

After the Docket bean is defined, its select() method returns an instance of ApiSelectorBuilder, which provides a way to control the endpoints exposed by Swagger.

Predicates for selection of RequestHandlers can be configured with the help of RequestHandlerSelectors and PathSelectors. Using any() for both will make documentation for your entire API available through Swagger.

This configuration is enough to integrate Swagger 2 into existing Spring Boot project. For other Spring projects, some additional tuning is required.

4.2. Configuration Without Spring Boot

Without Spring Boot, you don’t have the luxury of auto-configuration of your resource handlers. Swagger UI adds a set of resources which you must configure as part of a class that extends WebMvcConfigurerAdapter, and is annotated with @EnableWebMvc.

4.3. Verification

To verify that Springfox is working, you can visit the following URL in your browser:

http://localhost:8080/spring-security-rest/api/v2/api-docs

The result is a JSON response with large number of key-value pairs, which is not very human-readable. Fortunately, Swagger provides Swagger UI for this purpose.

5. Swagger UI

Swagger UI is a built-in solution which makes user interaction with the Swagger-generated API documentation much easier.

5.1. Enabling Springfox’s Swagger UI

To use Swagger UI, one additional Maven dependency is required:

Now you can test it in your browser by visiting http://localhost:8080/your-app-root/swagger-ui.html

In our case by the way, the exact URL will be: http://localhost:8080/spring-security-rest/api/swagger-ui.html

The result should look something like this:

5.2. Exploring Swagger Documentation

Within Swagger’s response is a list of all controllers defined in your application. Clicking on any of them will list the valid HTTP methods (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).

Expanding each method provides additional useful data, such as response status, content type, and a list of parameters. It is also possible to try each method using the UI.

Swagger’s ability to be synchronized with your code base is very important. To demonstrate this, you can add a new controller to your application.

Now, if you refresh the Swagger documentation, you will see custom-controller in the list of controllers. As you can see, there is only one method (POST) shown in Swagger’s response.

6. Advanced Configuration

The Docket bean of your application can be configured to give you more control over the API documentation generation process.

6.1. Filtering API for Swagger’s Response

It is not always desirable to expose the documentation for your entire API. You can restrict Swagger’s response by passing parameters to the apis() and paths() methods of the Docket class.

As seen above, RequestHandlerSelectors allows using the any or none predicates, but can also be used to filter the API according to base package, class annotation, and method annotations.

PathSelectors provides additional filtering with predicates which scan the request paths of your application. You can use any(), none(), regex(), or ant().

In the example below we will instruct Swagger to include only controllers from a specific package, with specific paths, using the ant() predicate.

6.2. Custom Information

Swagger also provides some default values in its response which you can customize, such as “Api Documentation”, “Created by Contact Email”, “Apache 2.0”.

To change these values, you can use the apiInfo(ApiInfo apiInfo) method. The ApiInfo class that contains custom information about the API.

6.3. Custom Methods Response Messages

Swagger allows globally overriding response messages of HTTP methodsthrough Docket’s globalResponseMessage() method. First, you must instruct Swagger not to use default response messages.

Suppose you wish to override 500 and 403 response messages for all GET methods. To achieve this, some code must be added to the Docket’s initialization block (initial code is excluded for clarity):

7. Conclusion

In this tutorial we set up Swagger 2 to generate documentation for a Spring REST API. We also have explored ways to visualize and customize Swagger’s output.

The full implementation of this tutorial can be found in the github project – this is an Eclipse based project, so it should be easy to import and run as it is.

最新文章

1. SC.UI
2. LGLSearchBar
3. 求次短路 codevs 1269 匈牙利游戏
4. ☆☆在Eclipse中编译NDK的so文件(普通安卓项目转换为NDK项目的设定)
5. c++中的243、251、250错误原因
6. C#读取xlsx文件Excel2007
7. Microsoft .NET Framework 4.0安装时发生严重错误 无法安装
8. javascript-ajax学习
9. Android开发经验之—intent传递大数据
10. android4.4组件分析--service组件-bindService源代码分析
11. 【转】简单的java缓存实现
12. ajax高级操作
13. 阿里云单机快速部署K8S
14. Git查看远程提交状态的方法
15. stl中的for_each() 函数的注意事项
16. LeetCode--219、268、283、414、448 Array(Easy)
17. Oracle事务隔离级别处理差异
18. Setting an Event to Null
19. Ubuntu终端快捷键使用
20. XE6 c++builder Edit垂直居中

热门文章

1. zabbix安装脚本
2. react-native 新手爬坑经历(unable to load script from assets 和could not connect to development server.)
3. 云笔记项目-网页端debug功能学习
4. Linux firewalld使用教程+rhce课程实验
5. CentOS 7升级Python到3.5后yum出错
6. grafana add custom dashboard
7. AI绘制毛线的小技巧
8. Apache beam中的便携式有状态大数据处理
9. AX_InventDim
10. 基于OpenCV的图书扫描识别程序开发