springboot 集成swagger

1.pom.xml加入Swagger依赖包

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <swagger.version>2.2.2</swagger.version>
    </properties>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

2.编写config配置类

@Configuration   //表明该类是配置类，并创建bean由spring管理
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //采用包含注解的方式来确定要显示的接口
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //采用包扫描的方式来确定要显示的接口
                //.apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题")
                .description("Swagger描述")
                .termsOfServiceUrl("www.baidu.com")
                .contact("actor")
                .version("1.0")
                .build();
    }

}

3.添加swagger注解

由于swagger是侵入式的，但好在只需要添加相关注解，无需改动其他代码，所以即使是旧工程新引入swagger的改动也是可以接受的

@RestController
@Api
public class GirlController {
    private final  static Logger logger = LoggerFactory.getLogger(GirlController.class);
    @Autowired
    private GirlRepository girlRepository;
    @Autowired
    private GirlService girlService;

    //查询一个女生
    @GetMapping(value = "/girls/{id}")
    @ApiOperation(value = "测试查询", notes = "测试根据id查询girl", tags = {""}, response = Girl.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "girl的id", name = "id", required = true, dataType = "int", paramType = "path"),
    })
    public Girl girlFindOne(@PathVariable("id") Integer id){
        return girlRepository.findOne(id);
    }

    //查询一个女生
    @PostMapping(value = "/girls/detail")
    @ApiOperation(value = "测试查询", notes = "测试根据id查询girl", tags = {""}, response = Girl.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "girl的id", name = "map", required = true, dataType = "map", paramType = "body"),
    })
    public Girl girlFindOnepost(@RequestBody Map<String,Object> map){
        Integer id = (Integer) map.get("id");
        System.out.println(id);
        return girlRepository.findOne(id);
    }

    //更新一个女生
    @PutMapping (value = "/girls/{id}")
    public Girl girlUpdateOne(@PathVariable("id") Integer id,
                              @RequestParam("cupSize") String cupSize,
                              @RequestParam("age") Integer age){
        Girl girl = new Girl();
        girl.setCupSize(cupSize);
        girl.setAge(age);
        girl.setId(id);
        return girlRepository.save(girl);
    }

    //删除一个女生
    @DeleteMapping(value = "/girls/{id}")
    public void deleteGirl(@PathVariable("id") Integer id){
         girlRepository.delete(id);
    }
    //根据年龄查询
    @GetMapping(value = "/girls/age/{age}")
    public List<Girl> girlFindByAge(@PathVariable("age") Integer age){
        return girlRepository.findByAge(age);
    }
    //测试swagger
    @RequestMapping(value = "/test/sw/{num}", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "测试Swagger", notes = "测试SwaggerNotes", tags = {""}, response = String.class)
    @ApiImplicitParams({
            @ApiImplicitParam(value = "测试字符串", name = "str", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(value = "测试数字", name = "num", required = true, dataType = "int", paramType = "path"),
    })
    public String swaggerTest(@RequestParam String str,@PathVariable Integer num){
        return str + num.toString();
    }
}

4.启动工程，访问：(http://localhost:8080/swagger-ui.html) ，就看到swagger-ui:

swagger.png

然后就可以做一些接口测试了。

Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

l   **code**：数字，例如400

l   **message**：信息，例如"请求参数没填好"

l   **response**：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

l   **@ApiModelProperty**：描述一个model的属性

常用注解可以参考：Swagger 常用注解使用详解