springboot整合swagger2

什么是Swagger2

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：

• 接口的文档在线自动生成；

• 功能测试；

为什么是swagger2

目前的项目基本都是[前后端分离,后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。 

常用注解

注解	描述
@Api	将类标记为 Swagger 资源。
@ApiImplicitParam	表示 API 操作中的单个参数。
@ApiImplicitParams	允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel	提供有关 Swagger 模型的其他信息。
@ApiModelProperty	添加和操作模型属性的数据。
@ApiOperation	描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam	为操作参数添加额外的元数据。
@ApiResponse	描述操作的可能响应。
@ApiResponses	允许多个 ApiResponse 对象列表的包装器。
@Authorization	声明要在资源或操作上使用的授权方案。
@AuthorizationScope	描述 OAuth2 授权范围。

导入依赖

<dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.1.RELEASE</version>
</dependency>
<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.7.8</version>
</dependency>

创建Swagger配置类

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    //api接口包扫描路径
    public static final String
            SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
    //指定当前Swagger API文档版本
    public static final String VERSION = "1.0.0";
​
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                .select()
                // 方法需要有ApiOperation注解才能生存接口文档
                //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径使用any风格
                .paths(PathSelectors.any())
                .build();
    }
​
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot中使用Swagger2构建RestFul APIs")
                .description("测试系统")
                //.termsOfServiceUrl("http://www.**.com")
                .version(VERSION)
                .build();
    }
​
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

1) 完成以上配置之后，通过mybatis-generator生成model和mapper；
2) 创建IBookService及BookServiceImpl实现类；
3) 创建BookController

综合案例

 

@Api

@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

案例演示

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
            produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){
    try {
        return bookService.queryAll();
    } catch (Exception e) {
        e.printStackTrace();
        return new JsonResponseBody<>(500,e.getMessage());
    }
}

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

案例演示

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
    JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);
    return json.getData();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
            ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
            @ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
            @ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
            @ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
                                   @RequestParam Double price,
                                   @RequestParam String booktype){
    return bookService.insert(Book.builder()
        .bookid(UUID.randomUUID().toString().replace("-",""))
        .bookname(bookname)
        .booktype(booktype)
        .price(price)
        .build());
}

@ApiModel和@ApiModelProperty
@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；

@ApiModelProperty注解描述一个model的属性。

案例演示

Controller

@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
    return bookService.updateByPrimaryKey(book);
}

注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
​
    /**
     * 书本编号
     */
    @ApiModelProperty(value="书本编号")
    private String bookid;
​
    /**
     * 书本名称
     */
    @ApiModelProperty(value="书本名称")
    private String bookname;
​
    /**
     * 书本价格
     */
    @ApiModelProperty(value="书本价格")
    private Double price;
​
    /**
     * 书本类型
     */
    @ApiModelProperty(value="书本类型")
    private String booktype;
​
    private static final long serialVersionUID = 1L;
}

@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam、@PathVariable和@RequestHeader一起使用。

案例演示

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
            @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
            @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
            @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
      System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
    return new JsonResponseBody<>();
}

运行测试