SpringBoot集成Swagger

本文使用官方的依赖配置，也可以使用二次开发的版本配置：二次开发版配置

简介

Swagger是统一前后端接口文档API的工具，世界上最流行的RestFul风格的API文档框架，可以直接测试接口，支持多种语言

使用

环境：springBoot框架

1.添加依赖

• swagger2
• ui

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

2.配置启动

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
}

3.访问主页

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

详细配置

Swagger的bean实例docket，此处根据个人

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置了Swagger的docket实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.cp"))
                .build();
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("chen","http://www.baidu.com","2442384797@qq.com");
        return new ApiInfo(
                "chen的Api",//title
                "描述",
                "v1.0",//version
                "http://www.baidu.com",//termsOfServiceUrl
                contact,
                "Apache 2.0",//license
                "http://www.baidu.com",//licenseUrl
                new ArrayList<>()
        );
    }

}

源码解读

下图是Docket的有参构造

配置apiInfo
给apiInfo赋值，下图是apiInfo的带参他构造

配置扫描的方式
Docket类中的select()方法

调用select()后可以执行的操作

此处是扫描接口的方式，返回值是上图apis(）方法所需的参数

注释

• @Api()用于类；
  表示标识这个类是swagger的资源
  tags–表示说明
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiImplicitParam注解的dataType、paramType两个属性的区别？
@ApiImplicitParam(name = “id”,value = “用户id”,required = true,dataType = “int”,paramType = “body”)

dataType=“int” 代表请求参数类型为int类型，当然也可以是Map、User、String等；
paramType 代表参数应该放在请求的什么地方：

header-->放在请求头。请求参数的获取：@RequestHeader(代码中接收注解)
query-->用于get请求的参数拼接。请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
body-->放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
form（不常用）

使用swagger生成restfull风格接口文档