简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，可以更加方便地测试接口。

配置

添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

添加配置

在这里插入代码片swagger:
  title: xxx项目RESTful API
  description: 开发人员太懒，没有写描述
  version: 1.0
  contactName: lxt
  contactEmail:
  contactUrl:
  basePackageRest: com.qcby.xxx.rest
  termsOfServiceUrl:

@Component
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {
    private String title;
    private String contactName;
    private String contactUrl;
    private String contactEmail;
    private String version;
    private String description;
   private String basePackageRest;
   private String termsOfServiceUrl;
   .... 省略get  set方法
}

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties swaggerProperties;

//    Predicate<RequestHandler> predicate = new Predicate<RequestHandler>() {
//        @Override
//        public boolean apply(RequestHandler input) {
//            if (input.isAnnotatedWith(ApiOperation.class))//只有添加了ApiOperation注解的method才在API中显示
//                return true;
//            return false;
//        }
//    };

    @Bean
    public Docket createRestApi() {
//        List<Parameter> parameters = new ArrayList<>();
//        parameters.add(new ParameterBuilder()
//                .name("token").defaultValue("testToken")
//                .description("认证token(需要登录可访问接口必须传参数)")
//                .modelRef(new ModelRef("string"))
//                .parameterType("header")
//                .required(false)
//                .build());

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("REST接口")
                .apiInfo(apiInfo())
//                .globalOperationParameters(parameters)
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackageRest()))
//                .apis(predicate)
                .build();
//        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(),swaggerProperties.getContactEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .build();
    }
}

使用

使用@ApiModelProperty标记Swagger要解析的实体类的属性。

@Builder
@Data
@TableName("ref_vedio_file")
public class VedioFile {
    @ApiModelProperty(value = "序号")
    @TableId(type = IdType.AUTO)
    private Long id;

    @ApiModelProperty(value = "视频id")
    private Long vedioId;

    @ApiModelProperty(value = "文件Id")
    private Long fileId;

    @ApiModelProperty(value = "文件名称")
    private String vedioFile;

    @ApiModelProperty(value = "排序字段")
    private int sort;

    @ApiModelProperty(value = "创建时间")
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
}

使用@Api注解标记在controller层中每个类上，用来表示对这个类的说明

@RestController
@Api(value = "视频相关业务控制", tags = {"前端接口-前端视频接口"})
@RequestMapping("vedioFront")
public class VedioFrontController {

}

使用@ApiOperation、@ApiImplicitParams和@ApiParam注解标记controller层中每个方法。
@ApiOperation：说明该方法的作用
@ApiImplicitParams：对该方法的参数的说明
@ApiParam：对该方法参数的说明

    /**
     * 通过id查询视频的详情信息
     * @param id
     * @return
     */
    @ApiOperation(value = "视频详情-通过id查询视频的详情信息")
    @ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
    @PostMapping("/private/selectVedioById/{id}")
    public ResultJson selectVedioById(@ApiParam(name="id",value="视频id",required = true)@PathVariable Long id) {
        Vedio vedio = vedioService.selectVedioById(id);
        return ResultJson.ok(vedio);
    }