springboot+swagger2说明

swagger用于定义API文档。

优势：

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件

添加pom依赖

    io.springfox
    springfox-swagger2
    2.2.2


    io.springfox
    springfox-swagger-ui
    2.2.2

Swagger2Config初始化配置如下：

package com.gasq.travel.config;

import com.gasq.travel.common.CodeEnum;
import com.gasq.travel.utils.collections.ListUtils;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

/**
 * @description: swagger2配置文件类
 * @访问路径： 如 http://localhost:8080/swagger-ui.html
 * @author fanpeng
 * @create 2017-01-03 10:00
 * @Modify By:
 **/
@Configuration
@EnableSwagger2
@ConfigurationProperties
public class Swagger2Config {
    @Value("${swagger.version}") private String version;
    @Value("${swagger.basePackage}") private String basePackage;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("travel")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET,customerResponseMessage())
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("国安社区-travel接口")
                .description("I'm description..")
                .contact("东哥")
                .version(version)
                .license("国安社区")
                .licenseUrl("baidu.com")
                .build();
    }

    /**
     * 自定义返回信息
     * @param
     * @return
     */
    private List customerResponseMessage(){
        return ListUtils.convertToList(
                new ResponseMessageBuilder()//500
                        .code(CodeEnum.error.getValue())
                        .message(CodeEnum.error.getDescription())
                        .responseModel(new ModelRef("Error"))
                        .build(),
                new ResponseMessageBuilder()//401
                        .code(CodeEnum.paramError.getValue())
                        .message(CodeEnum.paramError.getDescription())
                        .build());
    }


}

Controller中测试方法：

在这里我们使用@ApiOperation注解来声明此方法为要生成的接口文档，在配置中已经配置过了，如果不想方法生成文档，不加此注解即可；

配置中已经使用了自定义的响应信息，所以可以不设置@ApiResponses；

    @ApiOperation(value="测试日志程序", notes="测试日志程序", produces = "application/json")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "school", value = "学校名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String")
    })
    @RequestMapping(value = "/get",method = RequestMethod.GET)
    public void testProgram(HttpServletRequest request, HttpServletResponse response){
        logger.debug("debug");
        logger.info("info");
        logger.error("error");
        logger.warn("warn");

        Student student = studentCommandService.selectById(1);
//        Student student = studentCommandService.queryById(1l);
        System.out.println(student.toString());
        this.renderJson(CodeEnum.success.getValue(),CodeEnum.success.getDescription(),student,request,response);
    }

注解说明：

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  • paramType：参数放在哪个地方
    • header-->请求参数的获取：@RequestHeader
    • query-->请求参数的获取：@RequestParam
    • path（用于restful接口）-->请求参数的获取：@PathVariable
    • body（不常用）
    • form（不常用）
  • name：参数名
  • dataType：参数类型
  • required：参数是否必须传
  • value：参数的意思
  • defaultValue：参数的默认值
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类
• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  • @ApiModelProperty：描述一个model的属性

以上这些就是最常用的几个注解了。

需要注意的是：

• ApiImplicitParam这个注解不只是注解，还会影响运行期的程序，例子如下：

　　

如果ApiImplicitParam中的phone的paramType是query的话，是无法注入到rest路径中的，而且如果是path的话，是不需要配置ApiImplicitParam的，即使配置了，其中的value="手机号"也不会在swagger-ui展示出来。

 

具体其他的注解，查看：

https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

生成文档效果： 果

方法效果：

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，就能看到上文所展示的RESTful API的页面。