Springboot 整合swagger2

1、依赖

   <!--Swagger2依赖-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- 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>

2、配置

//表示是一个spring配置类
@Configuration
//开启swagger2
@EnableSwagger2
public class SwaggerConfig {

    @Bean
//    固定写法，如果要分多组，就返回多个Docket
    public Docket setDocket2(Environment environment){

//        多环境配置下，判断是否pro环境。
        Profiles of = Profiles.of("pro");
        boolean b = environment.acceptsProfiles(of);
        System.out.println(b);


        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("文档1")//文档组名
                .enable(!b)//是否显示
                .apiInfo(apiInfo())
                .select()
                .paths(PathSelectors.any())//路径过滤
                .apis(RequestHandlerSelectors.basePackage("com.doubleh.controller"))//加载选择
                .build();
    }

    private ApiInfo apiInfo() {
//        swagger文档描述
        return new ApiInfoBuilder()
                .title("文档标题") //文档的标题
                .description("描述描述")//文档描述
                .version("v1.0") // 文档的版本信息
                .build();
    }
}

3、常用属性

　　@Api(description ="说明")

　　　　常用于标注接口类，其他参数不显示；

　　@ApiOperation(value = "获取一本书",notes = "查询接口")

　　　　常用于标注方法，notes 可略，展开显示内容；

 　　@ApiParam()

　　　　用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等） 【暂时没用，当前使用SpringMVC@RequestParam】

　　@ApiIgnore

　　　　用于类，方法，方法参数 表示这个方法或者类被忽略

　　@ApiImplicitParam(name = "bookName", value = "用户标识", required = true, paramType = "query", dataType = "String") 

　　　　用于方法 表示单独的请求参数

　　@ApiImplicitParams() 

　　　　用于方法，包含多个 @ApiImplicitParam 

 

　　@ApiModel(value="值", description="说明")

　　　　常用于标注实体类

　　@ApiModelProperty(value = "值",example = "示例")

　　　　常用语标注实体类属性【注意实现：属性必须设置getter方法，否则不会显示】

4、实体类

　　getter方法一定要有，不然属性不会显示；

@ApiModel(value="Book", description="书籍类")
public class Book {
    @ApiModelProperty(value = "书籍id",example = "1")
    private int bookID;
    @ApiModelProperty(value = "书名",example = "钢铁是怎么样炼成的")
    private String bookName;
    @ApiModelProperty(value = "书籍数量",example = "100")
    private int bookCounts;
    @ApiModelProperty(value = "书籍介绍",example = "这是一本讲述怎样炼就钢铁之躯的书")
    private String detail;

    public Book() {
    }

    public Book(int bookID, String bookName, int bookCounts, String detail) {
        this.bookID = bookID;
        this.bookName = bookName;
        this.bookCounts = bookCounts;
        this.detail = detail;
    }

    public int getBookID() {
        return bookID;
    }

    public void setBookID(int bookID) {
        this.bookID = bookID;
    }

    public String getBookName() {
        return bookName;
    }

    public void setBookName(String bookName) {
        this.bookName = bookName;
    }

    public int getBookCounts() {
        return bookCounts;
    }

    public void setBookCounts(int bookCounts) {
        this.bookCounts = bookCounts;
    }

    public String getDetail() {
        return detail;
    }

    public void setDetail(String detail) {
        this.detail = detail;
    }

    @Override
    public String toString() {
        return "Book{" +
                "bookID=" + bookID +
                ", bookName='" + bookName + '\'' +
                ", bookCounts=" + bookCounts +
                ", detail='" + detail + '\'' +
                '}';
    }
}

5、控制器

　　如果参数是个对象且对象由swagger标注了，会自动引用。

@RestController()
@RequestMapping("/book")
@Api(description = "书籍接口")
public class BookController {

    @ApiOperation(value = "获取一本书",notes = "查询接口")
    @ApiImplicitParam(name = "bookName", value = "用户标识", required = true, paramType = "query", dataType = "String")
    @GetMapping("/{bookName}")
    public String book(@PathVariable String bookName){
        return bookName;
    }

    @ApiOperation(value = "新增一本书",notes = "新增接口")
    @PostMapping()
//    不是基础类型可以不标注，如果类有标注对自动引用
    public String book(@RequestBody Book book){
        return book.toString();
    }
}