Spring Boot中使用springfox Swagger2构建强大的RESTful API文档

maven依赖

    <!--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>
</dependencies>

自定义配置文件config

package cn..api.web.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableSwagger2
public class Swagger2 {

    @Value("${server.servlet-path}")
    private String contextPath;

    // 开关
    @Value("${swagger.enable}")
    private Boolean enable = false;

    @Bean
    public Docket createRestApi() {

        ParameterBuilder hotelIdParam = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        pars.add(hotelIdParam.name("hotelId").description("门店id").
                modelRef(new ModelRef("long")).
                parameterType("header").
                required(false).build());
        pars.add(hotelIdParam.name("agencyId").description("总部id").
                modelRef(new ModelRef("long")).
                parameterType("header").
                required(false).build());
        pars.add(hotelIdParam.name("orgId").description("机构Id").
                modelRef(new ModelRef("long")).
                parameterType("header").
                required(false).build());
        pars.add(hotelIdParam.name("agencyType").description("机构类型").
                modelRef(new ModelRef("byte")).
                parameterType("header").
                required(false).build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn..api.web"))
                .paths(enable ? PathSelectors.any() : PathSelectors.none())
                .build().globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("会员服务 WEB API")
                .description("根路径：" + contextPath)
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

注解说明

使用 @Api(description = "接口描述”) 注解接口类
使用 @ApiOperation(value = “方法描述", notes = "附加描述") 注解接口类中的方法
使用 @ApiModel(description = “实体类描述”) 注解方法参数/返回值实体类
使用 @ApiModelProperty(value = “字段”) 注解实体类中的字段

注解示例

接口类示例

package cn..web.equities.controller;

import cn.px.irs.commons.gateway.controller.BaseController;
import cn.px.irs.commons.tools.response.PageResponse;
import cn.px.irs.commons.tools.response.Response;
import cn.px.irs.eos.api.web.equities.consumer.RechargeRuleConsumer;
import cn.px.irs.eos.api.web.equities.vo.HotelVO;
import cn.px.irs.eos.api.web.equities.vo.RechargeRuleListVO;
import cn.px.irs.eos.api.web.equities.vo.RechargeRuleVO;
import cn.px.irs.eos.api.web.equities.vo.request.RechargeRequest;
import cn.px.irs.eos.api.web.equities.vo.request.RechargeRuleRequest;
import cn.px.irs.eos.common.dto.equities.HotelDTO;
import cn.px.irs.eos.common.dto.equities.RechargeRuleDTO;
import cn.px.irs.eos.common.dto.equities.recharge.RechargeGiftDTO;
import cn.px.irs.eos.common.dto.equities.recharge.RechargeGiftResult;
import cn.px.irs.eos.util.BeanUtil;
import cn.px.irs.eos.util.ValidUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;
import java.util.List;

@Api(description = "储值规则接口")
@Slf4j
@RestController
public class RechargeRuleController extends BaseController {

    private final RechargeRuleConsumer rechargeRuleConsumer;

    @Autowired
    public RechargeRuleController(RechargeRuleConsumer rechargeRuleConsumer) {
        this.rechargeRuleConsumer = rechargeRuleConsumer;
    }

    @ApiOperation(value = "获取储值规则列表", notes = "不分页")
    @GetMapping(value = "/recharge-rule/list")
    public PageResponse<RechargeRuleListVO> getRechargeRule(
            @RequestParam("start") Integer start,
            @RequestParam("size") Integer size) throws Exception {
        PageResponse<RechargeRuleDTO> rechargeRule = rechargeRuleConsumer.getRechargeRule(getOrgId(),
                getHotelId(), getAgencyType(), start, size);
        return BeanUtil.transformPageResponseBean(rechargeRule, RechargeRuleListVO.class);
    }
}

实体类示例

package cn..api.web.equities.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

@Data
@ApiModel(description = "积分规则列表数据")
public class RechargeRuleListVO {
    @ApiModelProperty(value = "储值规则id")
    private Long id;
    @ApiModelProperty(value = "储值规则名称")
    private String name;
    @ApiModelProperty(value = "赠送方式，1固定2按比例")
    private Byte giftType;
    @ApiModelProperty(value = "消费方式，1按比例2先主3先增")
    private Byte consumeType;
    @ApiModelProperty(value = "适用门店")
    private List<HotelVO> hotelDTOS;
    @ApiModelProperty(value = "规则描述")
    private String ruleDesc;
}

固定配置文件application.yml

#server
server:
  port: 8800
  servlet-path: /eos-api-web

#spring
spring:
  application:
    name: eos-api-web

#swagger    
swagger:
 enable: true

访问URL

配置结束后，启动项目，访问URLhttp://ip:port/swagger-ui.html/servlet-path/class/method
例如上述示例中的URL为http://127.0.0.1:8800/swagger-ui.html/eos-api-web/recharge-rule/list