SpringBoot的Swagger入门

1.导入依赖

    
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>
        <dependency>
            <groupId>javax.xml.bindgroupId>
            <artifactId>jaxb-apiartifactId>
            <version>2.3.0version>
        dependency>

2.创建配置类

@Configuration      //标明是配置类，让spring启动时加载
@EnableSwagger2     //启用Swagger2
public class SwaggerConfig {

    //创建多个方法并用Bean注解，这样就可以针对不同的Controller创建出各自的API文档，当创建多个API时，需要指定API的名称
    //这里如果函数上面不配置@Bean注解，那么Swagger只是启动了。没有创建API信息
    @Bean//IOC
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //.groupName("cus")
                .apiInfo(apiInfo())//apiInfo()用来创建Api基本信息
                .select()  // 选择那些路径和api会生成document，返回一个Api
                .apis(RequestHandlerSelectors.basePackage("com.example.controllers")) // 对所有api进行监控
                .paths(PathSelectors.any()) // 对所有路径进行监控
                .build();

    }

    /**
     * 创建Api信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目标题")
                .description("项目描述")
                .version("项目版本1.0")
                .build();
    }

}

3.Controller的配置

@Api(value = "/test",tags = "TestSwaggerController模块")
@RestController
@RequestMapping("/test")
public class TestSwaggerController {
    @Resource(name="userBiz")
    UserBiz userBiz;

    //              value:方法描述      notes:方法提示内容
    @ApiOperation(value = "用户添加",notes = "方法的提示：用户添加")
    //               name-参数名    value:参数说明  required：是否必填  dataType：属性类型
    @ApiImplicitParam(name = "user",value = "User对象",paramType = "path",required = true,dataTypeClass = User.class)//paramType 有五个可选值 ：
    // path, query, body, header, form，表明数据来自哪里
    @PostMapping("addUser.action")//相当于@RequestMapping(value = "addUser.action",method = RequestMethod.POST)
    public JsonModel addUser(User user){
        userBiz.addUser(user);
        JsonModel jm = new JsonModel();
        jm.setCode(200);
        jm.setObj(user);
        return jm;
    }
}

4.API一览

 @Api：用在请求的类上，表示对类的说明
 tags="说明该类的作用，可以在UI界面上看到的注解"
 value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 @ApiOperation：用在请求的方法上，说明方法的用途、作用
 value="说明方法的用途、作用"
 notes="方法的备注说明"
 @ApiImplicitParams：用在请求的方法上，表示一组参数说明
 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
 name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：
@RequestHeader· query --> 请求参数的获取：
@RequestParam· path（用于restful接口）--> 请求参数的获取：
@PathVariable· body（不常用）
· form（不常用）    
dataType：参数类型，默认String，其它值dataType="Integer"       
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

5.接口配置

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数