Springboot集成Swagger2以及常见配置（无坑版）

这种整合的文章确实已经烂大街了，写他一方面是补充我的springboot系列，另一方面确实还有一部分小伙伴没用过。最重要的是，如果你忘记了这种整合的代码。可以随时查阅。

创新互联专业为企业提供桓仁网站建设、桓仁做网站、桓仁网站设计、桓仁网站制作等企业网站建设、网页设计与制作、桓仁企业网站模板建站服务，10多年桓仁做网站经验，不只是建网站，更提供有价值的思路和整体网络服务。

前言

现在的开发基本上都是前后端分离，前后端交互都是通过API文档。有了API文档大家各自开发，互不干扰。

1、传统方式

传统方式是文档设计好之后，分别发给前端和后端人员。这样有个缺点，接口信息一旦变化，文档就需要重新发送给前后端人员。无法做到实时。所以浪费时间和精力。

2、swagger方式

我们的后台应用集成了swagger之后，会自动暴露出我们的接口，而且这个接口形式还是通过restful风格发布的。一旦后端的接口有变化，会立刻显示出来，因此极大地提高了效率。

OK，基本上一句话就可以总结他的好处，那就是后端写的api文档可以通过swagger的形式实时的发布出来，供前端人员查看。

3、其他方式

swagger的页面说实话长得不好看，也有一些其他的方案，不是有很多bug，就是收费。目前swagger是使用的最多的。我目前也正在做这个样的开源项目，基于swagger做出类似于其他方案的页面，而且功能更加的强大。

一、代码整合

前提条件是要新建一个springboot项目。这点就不演示了。

第一步：添加依赖

 
 
 
 
    
  
  
  
  
  1.  
    2.   
  
  
  
  2.     io.springfox 
    3.   
  
  
  
  3.     springfox-swagger2 
    4.   
  
  
  
  4.     2.9.2 
    5.   
  
  
  
  5.  
    6.   
  
  
  
  6.  
    7.   
  
  
  
  7.     io.springfox 
    8.   
  
  
  
  8.     springfox-swagger-ui 
    9.   
  
  
  
  9.     2.9.2 
    10.   
  
  
  
  10.  
    11.

2.9.2的版本是用的最多的，具体的可以直接去maven的官网去搜索，找一个使用量最多的版本即可。

第二步：配置

新建config包，创建SwaggerConfig类

 
 
 
 
    
  
  
  
  
  1. @EnableSwagger2 
    2.   
  
  
  
  2. @Configuration 
    3.   
  
  
  
  3. public class Swagger2Config { 
    4.   
  
  
  
  4.     @Bean 
    5.   
  
  
  
  5.     public Docket createRestApi() { 
    6.   
  
  
  
  6.         return new Docket(DocumentationType.SWAGGER_2) 
    7.   
  
  
  
  7.              .apiInfo(apiInfo()) 
    8.   
  
  
  
  8.              .select() 
    9.   
  
  
  
  9.              //为当前包路径,控制器类包 
    10.   
  
  
  
  10.              .apis(RequestHandlerSelectors.basePackage("com.fdd.controller")) 
    11.   
  
  
  
  11.             .paths(PathSelectors.any()) 
    12.   
  
  
  
  12.              .build(); 
    13.   
  
  
  
  13.     } 
    14.   
  
  
  
  14.     //构建 api文档的详细信息函数 
    15.   
  
  
  
  15.     private ApiInfo apiInfo() { 
    16.   
  
  
  
  16.         return new ApiInfoBuilder() 
    17.   
  
  
  
  17.             //页面标题 
    18.   
  
  
  
  18.            .title("XX平台API接口文档") 
    19.   
  
  
  
  19.             //创建人 
    20.   
  
  
  
  20.            .contact(new Contact("冯冬冬", "http://www.javachat.cc",   
    21.   
  
  
  
  21.                  "3049352171@qq.com")) 
    22.   
  
  
  
  22.            //版本号 
    23.   
  
  
  
  23.           .version("1.0") 
    24.   
  
  
  
  24.            //描述 
    25.   
  
  
  
  25.           .description("系统API描述") 
    26.   
  
  
  
  26.           .build(); 
    27.   
  
  
  
  27.     } 
    28.

这里的配置也比较简单。这里有很多选项供我们去配置。如果我们的项目有多个组，只需要创建多个Docket即可。这时候扫描的包换成每个组的包路径。

第三步：controller类中配置

新建一个controller包，然后创建HelloController类

 
 
 
 
    
  
  
  
  
  1. @Api("Hello控制类") 
    2.   
  
  
  
  2. @RestController  
    3.   
  
  
  
  3. public class HelloController { 
    4.   
  
  
  
  4.     @GetMapping(value = "/user") 
    5.   
  
  
  
  5.     public User getUser(){ 
    6.   
  
  
  
  6.         return new User("愚公要移山","123456"); 
    7.   
  
  
  
  7.     } 
    8.   
  
  
  
  8.     @ApiOperation("可以指定参数的API") 
    9.   
  
  
  
  9.     @PostMapping("/param") 
    10.   
  
  
  
  10.     public String hello2(@ApiParam("用户名") String name){ 
    11.   
  
  
  
  11.         return "hello" + name; 
    12.   
  
  
  
  12.     } 
    13.   
  
  
  
  13. } 
    14.

这里我们可以看出，使用注解就可以对这个类、方法、字段等等进行解释说明。其他的字段还有很多，在使用的时候会有相应的提示，可以自己试一遍：

第四步：查看效果

访问:http://127.0.0.1:8080/swagger-ui.html即可。

这里就是最终的展示效果。OK，到这一步基本上就集成进来了。下面说一下可能会遇到的配置。

三、常见其他问题

1、Spring Security - 配置免认证访问

有时候我们的Springboot集成了SpringSecurity，这时候如果访问swagger的地址会自动跳转到登录页面。这是因为SpringSecurity对其进行了拦截。为此我们只需要在我们的SpringSecurity配置一下进行放行即可。

现在配置一下，进行放行。在config包下新建一个SpringSecurityConfig类

 
 
 
 
    
  
  
  
  
  1. @Configuration 
    2.   
  
  
  
  2. @EnableWebSecurity 
    3.   
  
  
  
  3. public class SpringSecurityConfig extends WebSecurityConfigurerAdapter { 
    4.   
  
  
  
  4.     @Override 
    5.   
  
  
  
  5.     protected void configure(HttpSecurity http) throws Exception { 
    6.   
  
  
  
  6.         http 
    7.   
  
  
  
  7.                 .authorizeRequests() 
    8.   
  
  
  
  8.                 .antMatchers("/swagger-ui.html").permitAll() 
    9.   
  
  
  
  9.                 .antMatchers("/webjars/**").permitAll() 
    10.   
  
  
  
  10.                 .antMatchers("/swagger-resources/**").permitAll() 
    11.   
  
  
  
  11.                 .antMatchers("/v2/*").permitAll() 
    12.   
  
  
  
  12.                 .antMatchers("/csrf").permitAll() 
    13.   
  
  
  
  13.                 .antMatchers("/").permitAll() 
    14.   
  
  
  
  14.                 .anyRequest().authenticated() 
    15.   
  
  
  
  15.                 .and() 
    16.   
  
  
  
  16.                 .formLogin() 
    17.   
  
  
  
  17.         ; 
    18.   
  
  
  
  18.     } 
    19.   
  
  
  
  19. } 
    20.

此时就可以正常的访问了。

2、为swagger设置jwt

这种方式比较简单，只需要一步即可。修改我们的swaggerConfig类即可。

 
 
 
 
    
  
  
  
  
  1. @EnableSwagger2 
    2.   
  
  
  
  2. @Configuration 
    3.   
  
  
  
  3. public class Swagger2Config { 
    4.   
  
  
  
  4.     @Bean 
    5.   
  
  
  
  5.     public Docket api() { 
    6.   
  
  
  
  6.         return new Docket(DocumentationType.SWAGGER_2) 
    7.   
  
  
  
  7.                 .apiInfo(apiInfo()) 
    8.   
  
  
  
  8.                 .securityContexts(Arrays.asList(securityContext())) 
    9.   
  
  
  
  9.                 .securitySchemes(Arrays.asList(apiKey())) 
    10.   
  
  
  
  10.                 .select() 
    11.   
  
  
  
  11.                 .apis(RequestHandlerSelectors.any()) 
    12.   
  
  
  
  12.                 .paths(PathSelectors.any()) 
    13.   
  
  
  
  13.                 .build(); 
    14.   
  
  
  
  14.     } 
    15.   
  
  
  
  15.     //构建 api文档的详细信息函数 
    16.   
  
  
  
  16.     private ApiInfo apiInfo() { 
    17.   
  
  
  
  17.         return new ApiInfoBuilder() 
    18.   
  
  
  
  18.                 //页面标题 
    19.   
  
  
  
  19.                 .title("XX平台API接口文档") 
    20.   
  
  
  
  20.                 //创建人 
    21.   
  
  
  
  21.                 .contact(new Contact("冯冬冬", "http://www.javachat.cc", 
    22.   
  
  
  
  22.                         "3049352171@qq.com")) 
    23.   
  
  
  
  23.                 //版本号 
    24.   
  
  
  
  24.                 .version("1.0") 
    25.   
  
  
  
  25.                 //描述 
    26.   
  
  
  
  26.                 .description("系统API描述") 
    27.   
  
  
  
  27.                 .build(); 
    28.   
  
  
  
  28.     } 
    29.   
  
  
  
  29.     private ApiKey apiKey() { 
    30.   
  
  
  
  30.         return new ApiKey("JWT", "Authorization", "header"); 
    31.   
  
  
  
  31.     } 
    32.   
  
  
  
  32.     private SecurityContext securityContext() { 
    33.   
  
  
  
  33.         return SecurityContext.builder().securityReferences(defaultAuth()).build(); 
    34.   
  
  
  
  34.     } 
    35.   
  
  
  
  35.  
    36.   
  
  
  
  36.     private List defaultAuth() { 
    37.   
  
  
  
  37.         AuthorizationScope authorizationScope  
    38.   
  
  
  
  38.          = new AuthorizationScope("global", "accessEverything"); 
    39.   
  
  
  
  39.         AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; 
    40.   
  
  
  
  40.         authorizationScopes[0] = authorizationScope; 
    41.   
  
  
  
  41.         return Arrays.asList(new SecurityReference("JWT", authorizationScopes)); 
    42.   
  
  
  
  42.     } 
    43.   
  
  
  
  43.  
    44.   
  
  
  
  44. } 
    45.

加了一些token验证的代码，比较简单，关于JWT的东西，可以私下了解。这里不赘述了。

3、隐藏Endpoint

有时候自己写的controller，或者是controller里面的接口方法不想让前端人员看到，我们可以隐藏即可。

第一：隐藏整个controller

 
 
 
 
    
  
  
  
  
  1. @ApiIgnore 
    2.   
  
  
  
  2. @RestController 
    3.   
  
  
  
  3. public class MyController { 
    4.   
  
  
  
  4.     //方法 
    5.   
  
  
  
  5. } 
    6.

第二：隐藏某个接口方法1

 
 
 
 
    
  
  
  
  
  1. @ApiIgnore 
    2.   
  
  
  
  2. @ApiOperation(value = "描述信息") 
    3.   
  
  
  
  3. @GetMapping("/getAuthor") 
    4.   
  
  
  
  4. public String getAuthor() { 
    5.   
  
  
  
  5.     return "愚公要移山"; 
    6.   
  
  
  
  6. } 
    7.

第三：隐藏某个接口方法2

 
 
 
 
    
  
  
  
  
  1. @ApiOperation(value = "描述信息", hidden = true) 
    2.   
  
  
  
  2. @GetMapping("/get") 
    3.   
  
  
  
  3. public LocalDate getDate() { 
    4.   
  
  
  
  4.     return LocalDate.now(); 
    5.   
  
  
  
  5. } 
    6.

OK，很多配置基本上就到这了。后续会继续补充。

本文转载自微信公众号「愚公要移山」，可以通过以下二维码关注。转载本文请联系愚公要移山公众号。

网站名称：Springboot集成Swagger2以及常见配置（无坑版）
标题链接：http://www.hantingmc.com/qtweb/news23/29323.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联

猜你还喜欢下面的内容

外贸网站建设知识

同城分类信息

眉山网站建设　　 　成都网站维护　　 　成都电商网站建设方案　　 　成都创新互联　　 　泸州洋跃建站　　 　成都画册设计公司　　 　达州博佩科技　　 　玄科环保　　 　成都网站建设　　 　雕琢时光　　 　微信开发　　 　香港虚拟主机空间　　 　成都二枢机房　　 　广汉锦华橡塑　　 　禾巨建站　　 　企业网站制作　　 　香港虚拟主机　　 　证企宝　　 　成都微信开发　　 　成都app开发