Swagger与SpringBoot整合

Swagger 虽然给开发者开发过程中增加了操作步骤，但是能够有在线调试，且当修改了相应接口时，不用去修改接口文档，直接修改注释即可，保证了一定的代码可读性，以及方便了前后端交互时的测试。
步骤：
1.先导入pom的依赖

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

2.springboot的配置

    @Configuration
    @EnableSwagger2
    public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("cn.ucmed.petra.pay.agent.controller")) //如果有多个包的话配置到父目录即可
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("XX服务")
                    .version("1.0")
                    .build();
        }
    }

3.在相应接口中添加注释

@Api(tags = "pay-agent")
@RestController
@Slf4j
@RequestMapping("/pay")
public class PayOrderController {
    /**
     * @ApiOperation：用在请求的方法上，说明方法的用途、作用
            value="说明方法的用途、作用"
            notes="方法的备注说明"
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

    @ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

    @ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
     * @return
     */

    /**
     *支付下单接口
     *
    */
    @ApiOperation(value = "支付下单", notes = "支付平台接口")
    @PostMapping(value = "/payorder", produces = {"application/json"})
    public Response<PayOrderRsp> payOrder(@ApiParam(value = "req", required = true) @RequestBody PayOrderReq payOrderParam) {
        payOrderParam.setHosFlag(payFlag);
        log.info("支付下单 req:--->"+payOrderParam.toString());
        Response<PayOrderRsp> response = payPost("pay", payOrderParam);
        log.info("支付下单 res:--->"+response.toJsonString());
        return response;
    }
}

4.在实体类(请求实体)中添加注释

@Data
public class PayOrderReq {

    @ApiModelProperty(value = "业务记录唯一Id", required = true)
    private String recordId;

    @ApiModelProperty(value = "交易详细内容", required = true)
    private String body;

    @ApiModelProperty(value = "交易金额，单位分", required = true)
    private String fee;

    @ApiModelProperty(value = "商品名称", required = true)
    private String goodsName;
}

5.返回实体

public class Response<T> {

    private int code = 0;
    private String message = "";
    private T data;

}

6.实体类

@Data
public class PayOrderRsp {

    @ApiModelProperty(value = "当面付平台订单号")
    private String outTradeNO;

    @ApiModelProperty(value = "业务记录唯一 Id")
    private String recordId;

    @ApiModelProperty(value = "h5 支付页面地址或者二维码串码小程序支付直接返回下单参数 json 支付串")
    private String url;

    @ApiModelProperty(value = "当下单类型为微信小程序时候返回")
    private String wxRequestPayment;
}

生成的API文档地址 ：http://ip:port/swagger-ui.html
生成的json格式的rest api文档地址：http://ip:port/v2/api-docs

还可以使用swagger2markup来生成api文档（暂时还没有用到，贴一个简书地址:https://www.jianshu.com/p/f0b1ed00c411）可以参考这篇文章。