一、导包

    <!--swagger  start-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>
    <!--swagger  end-->

二、编写配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Value("${spring.application.name}")
    private String applicationName;
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档，这里可以通过指定注解的方式来进行扫描
                .apis(RequestHandlerSelectors.basePackage("com.pingwazi.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description("接口文档")
                .version("1.0")
                .build();
    }
}

浏览器输入地址测试

http://localhost:8080/swagger-ui.html

常用注解

@Api(tags = "PmsBrandController") //标记在类上[controller类]
@ApiOperation("首页接口") //标记在方法上
@ApiModelProperty("状态码") //标记在字段上

image.png

支持自定义枚举

ResponseCode是一个自定义枚举，枚举中有两个字段（code、description），通过这种方式实现，最终展示给出来的就是[ 0/* 成功 /, -1/ 失败 */ ]

@Component
public class ResponseCodePropertyPlugin implements ModelPropertyBuilderPlugin {
    @Override
    public void apply(ModelPropertyContext context) {
        Optional<ApiModelProperty> annotation = Optional.absent();

        if (context.getAnnotatedElement().isPresent()) {
            annotation = annotation.or(ApiModelProperties.findApiModePropertyAnnotation(context.getAnnotatedElement().get()));
        }
        if (context.getBeanPropertyDefinition().isPresent()) {
            annotation = annotation.or(Annotations.findPropertyAnnotation(
                    context.getBeanPropertyDefinition().get(),
                    ApiModelProperty.class));
        }
        final Class<?> rawPrimaryType = context.getBeanPropertyDefinition().get().getRawPrimaryType();
        //过滤得到目标类型
        if (annotation.isPresent() && ResponseCode.class.isAssignableFrom(rawPrimaryType)) {
            //获取CodedEnum的code值
            ResponseCode[] values = (ResponseCode[]) rawPrimaryType.getEnumConstants();
            final List<String> displayValues = Arrays.stream(values).map(respCode -> Integer.toString(respCode.getCode())+"/* "+respCode.getDescpriotn()+" */").collect(Collectors.toList());
            final AllowableListValues allowableListValues = new AllowableListValues(displayValues, rawPrimaryType.getTypeName());
            //固定设置为int类型
            final ResolvedType resolvedType = context.getResolver().resolve(String.class);
            context.getBuilder().allowableValues(allowableListValues).type(resolvedType);
        }
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

@Getter
public enum ResponseCode {
    OK(0,"成功"),
    ERROR(-1,"失败");
    private int code;
    private String descpriotn;
    ResponseCode(int code,String descpriotn) {
        this.code = code;
        this.descpriotn=descpriotn;
    }
}

@Data
public class ApiData<T> implements Serializable {
    @ApiModelProperty("状态码")
    private ResponseCode statusCode;
    @ApiModelProperty("消息")
    private String msg;
    @ApiModelProperty("响应数据")
    private T data;

    public ApiData(ResponseCode statusCode, String msg, T data) {
        this.statusCode = statusCode;
        this.msg = msg;
        this.data = data;
    }

    public ApiData(ResponseCode statusCode, String msg) {
        this.statusCode = statusCode;
        this.msg = msg;
    }

    public ApiData() {
        this.statusCode=ResponseCode.OK;
        this.msg="成功";
    }
}

image.png