Swagger使用

1. 导入jar包

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

2. 创建配置类

SwaggerConfig.java

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {

    // A组
    @Bean
    public Docket docketA() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A组");
    }

    // B组
    @Bean
    public Docket docketB() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B组");
    }

    // 测试组
    @Bean
    public Docket createRestApi(Environment environment) {
        // 在dev/test环境中使用swagger，在prod环境中不使用。判断当前环境返回boolean
        boolean flag = environment.acceptsProfiles(Profiles.of("dev", "test"));

        return new Docket(DocumentationType.SWAGGER_2)
                // api信息
                .apiInfo(apiInfo())
                // 分组
                .groupName("测试组")
                // flag=false 不能再浏览器中访问
                .enable(flag)
                .select()
                // 扫描配置了@ApiOperation 注解的方法，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描全部
                // .apis(RequestHandlerSelectors.any())
                // 不扫描
                // .apis(RequestHandlerSelectors.none())
                // 扫描类上的指定的包，生成接口文档
                // .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                // 扫描类上的 @RestController 注解，生成接口文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // 过滤路径
                .paths(PathSelectors.any())
                .build();
    }

    // api信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("liqiju测试的Api")
                .description("wangpai-admin文档")
                .termsOfServiceUrl("https://www.wgame.io")
                .version("2.0.0")
                .build();
    }
}

3. 测试

http://localhost:8080/swagger-ui.html

4. 注解说明

注解	说明
@Api	用在类上，说明该类的主要作用
@ApiOperation	用在方法上，给API增加方法说明
@ApiImplicitParams	用在方法上，包含一组参数说明
@ApiImplicitParam	用来注解来给方法入参增加说明
@ApiResponses	用于表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel	用在实体类上，描述一个Model的信息
@ApiModelProperty	描述一个model的属性

5. 实例

User.java（实体类）

@ApiModel(description = "用户实体类")
@Data
@Entity
public class User {
    @ApiModelProperty(value = "主键id", notes = "自增主键id")
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    @ApiModelProperty(value = "用户名", notes = "用户名,unique")
    private String username;

    @ApiModelProperty(value = "年龄", notes = "年龄是整形")
    private Integer age;

    @ApiModelProperty(value = "邮箱")
    private String email;

    @ApiModelProperty(value = "创建时间")
    private LocalDateTime createTime;
}

UserController.java

@Api("用户管理类")
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;

    @ApiOperation(value = "获取指定用户信息", notes = "根据用户id获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.findUserById(id);
    }

    
    @ApiOperation("获取全部用户信息")
    @GetMapping("/all")
    public List<User> userList() {
        return userService.findAll();
    }

    
    @ApiOperation("分页查询用户信息")
    @ApiImplicitParams({
            // paramType=form表示表单数据， path表示url参数
            @ApiImplicitParam(name = "page", value = "表示第几页", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "size", value = "每页几条数据", required = true, dataType = "Integer", paramType = "path")
    })
    @GetMapping("/list")
    public List<User> userListPage(Integer page, Integer size) {
        Page<User> userPage = userService.findAll(PageRequest.of(page, size));
        List<User> userList = userPage.getContent();
        return userList;
    }
}