Swagger框架的基本使用

Swagger是一款非常优秀的一款RESTFUL接口的文档在线自动生成+功能测试功能软件。它可以帮助我们快速生成一套优雅的API文档。

一、集成Swagger框架

SSM框架集成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>

在POM文件中添加以上依赖。

    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"></mvc:resources>

    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

在Spring的配置文件中添加以上配置,这两行配置用于放行Swagger的静态资源，防止被MVC拦截。

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket SwaggerDocket(){
        Docket docket=new Docket(DocumentationType.SWAGGER_2);
        docket.select()
                .apis(RequestHandlerSelectors.basePackage("FrameWork.Controller"))
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("SSM框架整合Swagger")
                        .description("整合测试使用").version("1.0")
                        .contact(new Contact("xxx","127.0.0.1","xxxxxxxxx@qq.com"))
                        .termsOfServiceUrl("127.0.0.1/team").build());
        return docket;
    }
}

Docket对象里可以配置一些文档的信息，@EnableSwagger2注解表示启用Swagger,@Configuration注解表示该类是个配置类。

到目前为止Swagger和SSM框架的集成就已经完成了，访问/swagger-ui.html路径测试框架是否集成成功。

SpringBoot集成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>

第一步添加依赖到pom文件

@Configuration
@EnableSwagger2
public class SpringBootConfiguration {

    @Bean
    public Docket docket(){
        Docket docket=new Docket(DocumentationType.SWAGGER_2);
        docket.select()
                .apis(RequestHandlerSelectors.basePackage("com.knight"))
                .build().apiInfo(new ApiInfoBuilder()
                                .contact(new Contact("kinght","127.0.0.1","xxxxxxxxx@qq.com"))
                                .license("license")
                                .title("API文档")
                                .version("1")
                                .description("测试swagger")
                                .build());
        return docket;
    }

}

第二步配置Docket 对象信息。

到此SpringBoot集成Swagger框架就成功了。不过我在集成到SpringBoot的过程中碰到了一个问题，每次访问/swagger-ui.html路径时，控制台都会报错。

java.lang.NumberFormatException: For input string: ""

百度了一下，这貌似是Swagger2.9.0本身的一个BUG,添加以下依赖就可以解决了。

  <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>1.5.22</version>
    </dependency>
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
      <version>1.5.22</version>
    </dependency>

二、框架的基本使用

@RestController
@Api(tags = "管理用户")
public class UserController {

    @Autowired
    UserService userService;

    @PostMapping("/register")
    @ApiOperation("注册用户")
    @ApiImplicitParams({@ApiImplicitParam(name="request",value = "http请求")})
    @ApiResponse(code = 401,message = "拒绝访问，没有登录",examples=@Example({@ExampleProperty(value = "12",mediaType = "application/json")}))
    public AjaxResponse register(HttpServletRequest request) throws UnsupportedEncodingException {

        String code="123456";

        if(!code.equals(code))
        {
            return new AjaxResponse("300","验证码错误",null);
        }

        User u=userService.findUserByAccount(request.getParameter("account"));
        if(u!=null){
            return new AjaxResponse("300","账号已存在",null);
        }

        User user=new User();

        user.setAccont(request.getParameter("account"));
        user.setPassword(request.getParameter("password"));
        user.setPortrait("images/headImg01.jpg");
        user.setName("用户"+System.currentTimeMillis());
        user.setCrationDate(new Timestamp(System.currentTimeMillis()));
        user.setLastLoginTime(new Timestamp(System.currentTimeMillis()));

        boolean status=userService.register(user);

        if(status){
            HashMap<String,Object> res=new HashMap<>();
            res.put("token", JWTUtil.generateToken(user));
            res.put("user",user);
            return new AjaxResponse("200","注册成功",res);
        }
        return new AjaxResponse("500","注册失败",null);
    }

    @GetMapping("/login")
    @ApiOperation("登录接口")
    @ApiImplicitParams({@ApiImplicitParam(name="account",value = "账户名",required = true,defaultValue = "123456")
            ,@ApiImplicitParam(name="password",value="密码",required = true,defaultValue = "acbabsjcbas")})
    public AjaxResponse login(String account, String password) throws IOException {
        User user=userService.login(account,password);
        List<Object> list=null;
        if(user!=null){
            list=new ArrayList<>();
            list.add(user);
            Map<String,String> token=new HashMap<>();
            token.put("token",JWTUtil.generateToken(user));
            list.add(token);
        }
       return new AjaxResponse("200","success",list);
    }

}

@ApiModel(description = "响应格式")
public class AjaxResponse implements Serializable{
    @ApiModelProperty("状态码")
    private String code;
    @ApiModelProperty("返回消息")
    private String msg;
    @ApiModelProperty("响应数据")
    private Object data;

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    public AjaxResponse(String code, String msg, Object data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public AjaxResponse() {
    }
}

1. @Api注解用于标识控制器。
2. @ApiOperation注解用于标识Api接口
3. @ApiImplicitParams注解用于描述多个输入参数
4. @ApiImplicitParam注解踊跃描述的单个输入参数，可以单独使用
5. @ApiResponse注解用于标识响应格式
6. @ApiModel注解描述实体类，但只有当被标识的实体类作为返回参数时才会显示到文档中。
7. @ApiModelProperty注解描述实体类属性