Springboot2.x集成swagger2生成接口文档

朱雀 2021-05-10 11:33 649阅读 0赞

# Springboot2.x集成swagger2生成接口文档 #

## 1. 引入依赖 ##

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>

## 2. 编写Swagger2Config配置类 ##

package com.turing.team_website.configuration;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /** * @author Jack * @date 2019-07-08-19:05 */
    @EnableSwagger2
    @Configuration
    public class Swagger2Config { 
    
        @Bean
        public Docket createRestApi1(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("前台访客API文档")
                    .apiInfo(apiInfo1())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.turing.team_website.controller.guest"))
                    .paths(PathSelectors.any())
                    .build();
        }
        @Bean
        public Docket createRestApi2(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("后台管理API文档")
                    .apiInfo(apiInfo2())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.turing.team_website.controller.admin"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo1(){ 
            return new ApiInfoBuilder()
                    .title("图灵智能创新网站前台接口文档")
                    .version("1.0")
                    .build();
        }
    
        private ApiInfo apiInfo2(){ 
            return new ApiInfoBuilder()
                    .title("图灵智能创新团队网站后台管理接口")
                    .version("1.0")
                    .build();
        }
    
    }

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>解释</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@EnableSwagger2</td> 
   <td>开启swagger2</td> 
  </tr> 
  <tr> 
   <td>@Configuration</td> 
   <td>声明配置类</td> 
  </tr> 
  <tr> 
   <td>@Bean</td> 
   <td>注册到Spring容器中</td> 
  </tr> 
 </tbody> 
</table>

\#\#\#2.1 Docket(一个Docket对象就是一个大的接口文档)

<table> 
 <thead> 
  <tr> 
   <th>关键字</th> 
   <th>解释</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>groupName</td> 
   <td>该接口文档的命名, 显示在网页右上方</td> 
  </tr> 
  <tr> 
   <td>apiInfo</td> 
   <td>API的信息, 显示在接口上方</td> 
  </tr> 
  <tr> 
   <td>apis(RequestHandlerSelectors.basePackage(controller包的位置))</td> 
   <td>扫描swagger注解的controller包</td> 
  </tr> 
 </tbody> 
</table>

## 3. controller层注解使用 ##

<table> 
 <thead> 
  <tr> 
   <th>关键字</th> 
   <th>解释</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>标注在类上, 属性tags可指定该接口的名字</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>单个参数, 属性:name(参数名),value(参数解释说明),paramType(参数路径类型),dataType(参数数据类型)…</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>k可指定多个参数,用数组表示, 数组内是一个个@ApiImplicitParam注解</td> 
  </tr> 
 </tbody> 
</table>

## 4. controller层使用例子 ##

package com.turing.team_website.controller.guest;
    
    import com.turing.team_website.entity.JsonResult;
    import com.turing.team_website.entity.Member;
    import com.turing.team_website.service.guest.GuestMemberService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    import java.util.List;
    
    /** * @author Jack * @date 2019-07-08-14:39 */
    @Api(tags = "团队成员接口")
    @RestController
    @RequestMapping("/guest/member")
    public class GuestMemberController { 
    
        @Autowired
        GuestMemberService guestMemberService;
    
        @GetMapping("")
        public JsonResult findAllMembers(){ 
    
            List<Member> members = guestMemberService.findAllMembers();
            return JsonResult.success().add("members", members);
    
        }
    
        @ApiImplicitParam(name = "technology", value = "技术方向(前端,后台,计算机视觉,自然语言处理)",
                paramType = "query", dataType = "String", required = true)
        @GetMapping("/tech")
        public JsonResult findMembersByTech(@RequestParam(name = "technology") String technology){ 
    
            List<Member> members = guestMemberService.findMembersByTech(technology);
            return JsonResult.success().add("members", members);
    
        }
    
        @ApiImplicitParam(name = "memberId",value = "成员id" ,paramType = "path", dataType = "Integer", required = true)
        @GetMapping("/{memberId}")
        public JsonResult findMemberById(@PathVariable Integer memberId){ 
    
            Member member = guestMemberService.findMemberById(memberId);
            return JsonResult.success().add("member",member);
    
        }
    }

## 5. 页面展示 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTk0OTMyOA_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTk0OTMyOA_size_16_color_FFFFFF_t_70]: /images/20210509/4cd269f430c744f28df1b7db714f6ff8.png