SpringBoot使用Swagger2来在线自动生成接口文档

一：什么是Swagger

Swagger2是一款通过添加的注解来对方法进行说明，来自动生成项目的在线api接口文档的web服务

二：添加Swagger2依赖

 1 <!-- 添加Swagger2依赖 -->
 2         <dependency>
 3             <groupId>io.springfox</groupId>
 4             <artifactId>springfox-swagger2</artifactId>
 5             <version>2.9.2</version>
 6             <exclusions>
 7                 <exclusion>
 8                     <groupId>io.swagger</groupId>
 9                     <artifactId>swagger-models</artifactId>
10                 </exclusion>
11             </exclusions>
12         </dependency>
13         <dependency>
14             <groupId>io.springfox</groupId>
15             <artifactId>springfox-swagger-ui</artifactId>
16             <version>2.9.2</version>
17         </dependency>
18         <dependency>
19             <groupId>io.swagger</groupId>
20             <artifactId>swagger-models</artifactId>
21             <version>1.5.22</version>
22         </dependency>

三：创建Swagger2配置文件

在文件夹conf中创建SwaggerConfigurer

 1 package com.boc.houselease.conf;
 2 
 3 import org.springframework.context.annotation.Bean;
 4 import org.springframework.context.annotation.Configuration;
 5 import springfox.documentation.builders.ApiInfoBuilder;
 6 import springfox.documentation.builders.PathSelectors;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.service.ApiInfo;
 9 import springfox.documentation.service.Contact;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spring.web.plugins.Docket;
12 import springfox.documentation.swagger2.annotations.EnableSwagger2;
13 
14 @Configuration
15 @EnableSwagger2
16 public class SwaggerConfigurer {
17     @Bean
18     public Docket createRestApi() {
19         return new Docket(DocumentationType.SWAGGER_2)
20                 .apiInfo(apiInfo())
21                 .select()
22                 .apis(RequestHandlerSelectors.basePackage("com.boc.houselease.controller"))
23                 .paths(PathSelectors.any())
24                 .build();
25     }
26 
27     private ApiInfo apiInfo() {
28         return new ApiInfoBuilder()
29                 .title("房屋租赁API")
30                 .description("盐城分行租入房产管理项目API")
31 //                .termsOfServiceUrl("https://127.0.0.1:9003/getList")
32                 .contact(new Contact("zhealks", "https://www.cnblogs.com/zhealks", "symxkya_js@mail.notes.bank-of-china.com"))
33                 .version("1.0")
34                 .build();
35     }
36 
37 }

四：添加注解

在Application中引入@EnableSwagger2来启动swagger注解

 1 @SpringBootApplication
 2 @EnableScheduling
 3 @EnableSwagger2
 4 public class HouseleaseApplication {
 5 
 6     public static void main(String[] args) {
 7         SpringApplication.run(HouseleaseApplication.class, args);
 8     }
 9 
10 }

修改Controller，添加API注解

 1 @RestController
 2 @CrossOrigin(origins = "*")
 3 @RequestMapping("/fwzl/dept")
 4 @Api(tags = "机构管理模块")
 5 public class FwzlDeptVController {
 6     @Autowired
 7     private IFwzlDeptVService iFwzlDeptVService;
 8 
 9     @GetMapping("/tree")
10     @ApiOperation(value = "获取机构树")
11     public JSONArray getDeptTree(){
12         JSONArray deptJson =iFwzlDeptVService.getDeptJsonArray();
13         return deptJson;
14     }
15 }

注意：参数前需加上@RequestParam

注解可以查看参考swagger官方注解文档进行自定义添加

五：页面404问题

继承WebMvcConfigurationSupport之后，静态文件映射会出现问题，需要重新指定静态资源。在WebConfigurer中添加如下代码：

 1 package com.boc.houselease.conf;
 2 
 3 import org.springframework.context.annotation.Configuration;
 4 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 5 import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
 6 
 7 @Configuration
 8 public class WebConfigurer extends WebMvcConfigurationSupport {
 9     @Override
10     public void addResourceHandlers(ResourceHandlerRegistry registry) {
11         registry.addResourceHandler("swagger-ui.html")
12                 .addResourceLocations("classpath:/META-INF/resources/");
13         registry.addResourceHandler("/webjars/**")
14                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
15         registry.addResourceHandler("/favicon.ico")
16                 .addResourceLocations("classpath:/META-INF/resources/favicon.ico");
17         super.addResourceHandlers(registry);
18     }
19 
20 }

六：接口测试

浏览器输入<ip>:<port>/swagger-ui.html

posted on 2021-09-01 21:56 zhealks 阅读(458) 评论(0) 收藏举报