Springboot集成Swagger2

先说项目中集成Swagger的好处：不用手写API文档（手写文档维护较为困难）；可以模拟http请求，进行接口测试

操作步骤：

1、配置pom文件

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

2、配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("这里是要扫描的包名"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api文档")
                .description("springboot利用swagger构建api文档")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

• .select()  初始化并返回一个API选择构造器
• .apis(RequestHandlerSelectors.basePackage("com.*.controller"))  添加路径选择条件
• .paths(PathSelectors.any())   设置路径筛选
• .build();    构建

3、配置Controller

@Api(description = "用户接口")
@RestController
@RequestMapping("/user")
public class UserController {

     @ApiOperation(value = "新增用户" ,  notes="新增注册")
     @PostMapping("save")
     public ExtObject save(@RequestBody User user){
        return ExtObject.ok("注册成功",null);
     }

     @ApiOperation(value = "新增用户2" ,  notes="新增注册2")
     @PostMapping("save2")
     public ExtObject save2(@ModelAttribute User user){
        return ExtObject.ok("注册成功",null);
     }

     @ApiOperation(value = "查询用户" ,  notes="查询用户")
     @ApiImplicitParams({
         @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType= "query", dataType = "String")
     })
     @GetMapping("queryUserById")
     public ExtObject queryUserById(@RequestParam("userId") String userId){
        User user = new User(userId, "admin", "******");
        return ExtObject.ok("成功获取数据",user);
     }

}

• @Api()用于类； 表示标识这个类是swagger的资源
• @ApiOperation()用于方法； 表示一个http请求的操作
• @ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法 表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

4、对象类

@ApiModel(value="user", description="用户对象")
public class User {
    @ApiModelProperty(value="用户id",name="userId",example="1000001")
    private String userId;

    @ApiModelProperty(value="用户名",name="userName",example="admin")
    private String username;

    @ApiModelProperty(value="密码",name="password",example="123456")
    private String password;

    ...//略
}

• @ApiModel() 对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改 

5、查看效果

启动项目后访问 http://localhost:8080/swagger-ui.html

（注意：如项目配置登录拦截，查看文章最后的扩展部分）

点击user-controller可以看到详细接口

 

       点击具体接口可以查看接口详细参数

       点击  try it out!  可以测试接口

6、扩展

项目中一般都会配置登录拦截，在访问swagger-ui.html会被拦截

如项目中集成的shiro,解决方法如下：

        // 针对Swagger拦截放行
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/swagger/**", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");
        filterChainDefinitionMap.put("/configuration/**", "anon");