springboot利用swagger2构建api文档

现如今为了前后台更好的对接，也为了以后交接方便，基本上都有要求写API文档。

手写Api文档的几个痛点：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理
Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

一、依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

二、Swagger配置类
其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

package net.bjspace;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author BJ
 * @date 2018.04.20
 */
@Configuration
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("net.bjspace.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("http://blog.bjspace.net")
                .version("1.0")
                .build();
    }
}
用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

package net.bjspace;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwagger2Application.class, args);
    }
}

三、Restful 接口
package net.bjspace.controller;

import java.util.Map;
import javax.annotation.Resource;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.alibaba.fastjson.JSONObject;
import net.bjspace.service.CardDataService;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/**
 * @author BJ
 * @date 2018.04.20
 * @note 卡片
 */
@RestController
@RequestMapping("/cardData")
public class CardDataController {
    
    @Resource
    private CardDataService cardDataService;
    
    /**
     * @before 负载率
     * @param
     * @return
     */
    @ApiOperation(value="负载率", notes="根据id、日期获取负载率")
    @ApiImplicitParams({
        @ApiImplicitParam(name="id", value="id", required=true, dataType="String", paramType="path"),
        @ApiImplicitParam(name="date", value="日期（yyyy-MM-dd）", required=true, dataType="String", paramType="path")})
    @ResponseBody
    @RequestMapping(value = "/loadRateCard", method = RequestMethod.GET)
    public JSONObject loadRateCard(@RequestParam (value="id") String id, @RequestParam (value="date") String date) {
        JSONObject jsonObject = new JSONObject();
        Map<String, Object> map = cardDataService.loadRateCard(id, date, measType);
        jsonObject.put("code", 200);
        jsonObject.put("message", "获取成功");
        jsonObject.put("data", map);
        return jsonObject;
    }
    
    /**
     * @before 过载
     * @param
     * @return
     */
    @ApiOperation(value="过载", notes="根据id获取过载")
    @ApiImplicitParam(name="id", value="id", required=true, dataType="String", paramType="path")
    //当然这里也可以传入一个实体，如下：
    //@ApiImplicitParam(name = "user", value = "实体user", required = true, dataType = "User")
    @ResponseBody
    @RequestMapping(value = "/overload", method = RequestMethod.GET)
    public JSONObject overload(@RequestParam (value="id") String id) {
        JSONObject jsonObject = new JSONObject();
        Map<String, Object> map = cardDataService.overloadAndHeavy(id, date, "over");
        jsonObject.put("code", 200);
        jsonObject.put("message", "获取成功");
        jsonObject.put("data", map);
        return jsonObject;
    }
}

四、Swagger2文档
启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

说明：

• @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的属性