SpringBoot笔记--整合Swagger

一、上代码

0.pom.xml

 
    
        io.springfox
        springfox-swagger2 
        2.9.2
    
    
        io.springfox
        springfox-swagger-ui 
        2.9.2
    

1.Swagger2Conf

@Configuration
@EnableSwagger2
public class Swagger2Conf {
@Bean
public Docket getUserDocket(){
    ParameterBuilder parameterBuilder = new ParameterBuilder();
    List parameters = new ArrayList();
    parameterBuilder.name("X-Token").description("认证token") //Header里添加X-Token参数用于认证
            .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    parameters.add(parameterBuilder.build());

    ApiInfo apiInfo=new ApiInfoBuilder()
            .title("yx-server系统")//api标题
            .description("yx-server api 接口文档")//api描述
            .version("1.0.0")//版本号
            .build();
    return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
            .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
            .select()//启动用于api选择的构建器
            .apis(RequestHandlerSelectors.basePackage("com.yx.controller"))//扫描接口的包
            .paths(PathSelectors.any())//路径过滤器（扫描所有路径）
            .build().globalOperationParameters(parameters);
}

}

2.Controller注解示例

@RestController
@RequestMapping("/user")
@Api("用户管理")
public class UserController {

@Resource
UserServicesImpl userServices;

@ApiOperation("登录")
@RequestMapping(value = "/login", method = RequestMethod.POST)
public Object login(HttpServletResponse response,
                    @RequestParam(value = "username", required = true) String userName,
                    @RequestParam(value = "password", required = true) String password) {

    //用户认证信息
    Subject subject = SecurityUtils.getSubject();
    UsernamePasswordToken usernamePasswordToken = new UsernamePasswordToken(userName, password);
    try {
        //进行验证，这里可以捕获异常，然后返回对应信息
        subject.login(usernamePasswordToken);
        return ApiResult.success(subject.getSession().getId()); //将token返回给前端
    } catch (UnknownAccountException e) {
        return ApiResult.failure(ResponseCode.ACCOUNT_NOT_EXIST);
    } catch (AuthenticationException e) {
        return ApiResult.failure(ResponseCode.ACCOUNT_ERROR);
    }
}

}

3.POJO注解示例

@Data
@ApiModel("用户")
public class User {

  @ApiModelProperty("用户名")
  private String username;

  @ApiModelProperty("密码")
  @JsonProperty(access = JsonProperty.Access.WRITE_ONLY) //表示 Restful接口返回给前台时不包含该字段
  private String password;

  @ApiModelProperty("年龄")
  private Integer age;

  @ApiModelProperty("生日")
  @JsonFormat(pattern = "yyyy-MM-dd hh:mm:ss a", locale = "zh", timezone = "GTM+8")
  private Date birthday;

  @ApiModelProperty("描述")
  private String des;
}

二、访问swagger

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

image.png

三、 常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。

@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误的返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数
更多使用说明，参考 Swagger 使用手册。