Setting Up Swagger 2 with a Spring Boot REST API
来源:互联网 发布:域名name代表什么意思 编辑:程序博客网 时间:2024/05/16 05:41
1.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.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
2.Integrating Swagger 2 into the Project
2.1.Java Configuration
The 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.
2.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.
2.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 a large number of key-value pairs, which is not very human-readable. Fortunately, Swagger provides Swagger UI for this purpose.
3.Swagger UI
Swagger UI is a built-in solution which makes user interaction with the Swagger-generated API documentation much easier.
3.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/swagger-ui.html
In our case, by the way, the exact URL will be: http://localhost:8080/swagger-ui.html
The result should look something like this:
3.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 crucial. To demonstrate this, you can add a new controller to your application.
Now, if you refresh the Swagger documentation, you will see custom-controllerin the list of controllers. As you know, there is only one method (POST) shown in Swagger’s response.
4.Advanced Configuration
The Docket bean of your application can be configured to give you more control over the API documentation generation process.
4.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 the 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 particular package, with specific paths, using the ant() predicate.
4.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.
4.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 GETmethods. To achieve this, some code must be added to the Docket’s initialization block (original code is excluded for clarity):
5.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.
And, if you’re a student of REST With Spring, go to Lesson 1 from Module 7 for a deep-dive into setting up Swagger with Spring and Spring Boot.
6.The original address
http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
7.Source code download address
https://gitee.com/micai/micai-springmvc-swagger
阅读全文
0 0
- Setting Up Swagger 2 with a Spring Boot REST API
- Setting Up Swagger 2 with a Spring REST API
- 使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
- WP REST API: Setting Up and Using OAuth 1.0a Authentication
- spring-boot 集成 Swagger 搭建RESTful API
- spring boot swagger 分组 定制 显示API
- WP REST API: Setting Up and Using Basic Authentication
- spring boot rest接口自动生成文档(包含swagger)
- Securing REST APIs With Spring Boot
- Setting up a PHP 5 with Apache 2 and MySQL 4.1.3
- Setting up a windows PHP server with MSSQL
- <LearnWLS> Setting Up Examples to Run with a Derby Database
- 使用PHP创建一个REST API(Create a REST API with PHP) 节选2
- Spring Boot REST API错误处理指南
- Setting Up a RequestQueue
- Spring boot 中使用swagger-ui实现 restful-api
- swagger ui和spring boot集成生成api文档
- Spring boot结合swagger自动生成api文档
- 欢迎使用CSDN-markdown编辑器
- spring注解:@ComponentScan,@Bean,@Import,@Component
- Oracle PL/SQL Dev工具(破解版)被植入勒索病毒的安全预警及自查通告
- 知识星球作业(第5周)
- 选择排序法 Java实现
- Setting Up Swagger 2 with a Spring Boot REST API
- Vue 子组件的异步加载及其生命周期控制
- runOnUiThread 、Handler.post、View.post之间的区别
- 月薪过万的UI设计师有哪些能力
- oracle 精确到小数秒的timestamp类型分区表
- Python图像特征检测算法(1):Python实现SIFT和Harris
- Matlab 关于使用Deep Learning Toolbox 工具箱出错的问题
- [目标检测] faster-rcnn demo.py 解析
- react-redux使用小结