Swagger的简单使用

1、引入依赖

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

2、配置文件

@Configuration
@EnableSwagger2	//在启动类上或者配置类加 @EnableSwagger2 注解
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ziyu.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("子羽", "http://www.my.com", "[email protected]");
        return new ApiInfoBuilder()
                .title("前台接口")
                .description("这个博客666 ")
                .contact(contact)   // 联系方式
                .version("1.1.0")  // 版本
                .build();
    }
}

访问路径：http://localhost:7777/swagger-ui.html

效果：

3、常用注解

@Api：修饰整个类，描述Controller的作用

@RestController
@RequestMapping("/comment")
@Api(tags = "评论相关接口")
public class CommentController {
}

@ApiOperation：描述一个类的一个方法，或者说一个接口

属性：

• value：方法描述作用

• notes：方法笔记（展开描述）

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam：一个请求参数

    @ApiOperation(value = "评论列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum",value = "页号"),
            @ApiImplicitParam(name = "pageSize",value = "每页大小")
    	})
    @GetMapping("/commentList")
    public ResponseResult commentList(Long articleId,Integer pageNum,Integer pageSize){
        return commentService.commentList("0",articleId,pageNum,pageSize);
    }

@ApiParam：单个参数的描述信息

属性：

• name：参数名称

• value：描述参数作用

• required：值为boolean类型，表示该参数是否为必要参数，默认为false

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "添加评论dto")
public class AddCommentDto {
    private Long id;

    //评论类型（0代表文章评论，1代表友链评论）
    @ApiModelProperty(notes = "评论类型（0代表文章评论，1代表友链评论）")
    private String type;
    ...

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiError ：发生错误返回的信息

@ApiImplicitParam属性：