swagger2入门实例

1、maven依赖

 <!-- swagger2-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>

            <!-- swagger2-UI-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

创建Swagger2配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /** 是否开启swagger */
    @Value("${swagger.enabled}")
    private boolean enabled;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：XXXXX")
                // 描述
                .description("")
                // 作者信息
                .contact(new Contact("NiuCheKeJi", null, null))
                // 版本
                .version("版本号:" + 1.0)
                .build();
    }
}

配置文件

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true

Swagger使用的注解及其说明：

用于controller

注解	说明
@Api	对请求类的说明
@ApiOperation	方法的说明
@ApiImplicitParams	方法的参数的说明（多个）
@ApiImplicitParam	方法的参数的说明（一个）
@ApiResponses	方法返回值的说明（多个）
@ApiResponse	方法返回值的说明（一个）

用在JavaBean

注解	说明
@ApiModel	对JavaBean类的说明
@ApiModelProperty	属性的说明

@ApiOperation：方法的说明

@ApiOperation：“用在请求的方法上，说明方法的作用”
value=“说明方法的作用”
notes=“方法的备注说明”

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
· query --> 请求参数的获取：@RequestParam
· header --> 请求参数的获取：@RequestHeader
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（请求体）–> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

简单的使用

@ApiModel
@Data
public class TestVO {
    @ApiModelProperty("手机号")
    private String phone;
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("性别")
    private String sex;

}

@RequestMapping("/test")
@Api
@RestController
public class TestController {
    @GetMapping("/a")
    @ApiOperation("这是一个测试方法")
    @ApiImplicitParam(name = "a" ,value = "传入的参数",dataType = "String")
    public TestVO test(String a,@RequestBody TestVO testVO){
        System.out.println(a);
        return testVO;
    }
}

一般我们返回给前端的数据要包含：状态码，错误信息，数据。所以一般我们要创建一个封装类来封装数据。

@ApiModel
@Data
public class ApiResult<T> {
    @ApiModelProperty("返回码")
    private int code;
    @ApiModelProperty("data")
    private T object;
    @ApiModelProperty("返回错误信息")
    private String msg;

    public static <T> ApiResult<T> ok(T object) {
        return new ApiResult<T>(200, object, "成功");
    }

    public static <T> ApiResult<T> ok() {
        return new ApiResult<T>(200, null, "成功");
    }

    public static <T> ApiResult<T> fail() {
        return new ApiResult<T>(0, null, "失败");
    }

    public static <T> ApiResult<T> fail(String msg) {
        return new ApiResult<T>(0, null, StringUtils.isEmpty(msg) ? "操作失败" : msg);
    }


    private ApiResult(int code, T object, String msg) {
        this.code = code;
        this.object = object;
        this.msg = msg;
    }

    @Override
    public String toString() {
        return "PubObjectResult{" +
                "code=" + code +
                ", object=" + object +
                ", msg='" + msg + '\'' +
                '}';
    }
}

在对controller改进

@RequestMapping("/test")
@Api
@RestController
public class TestController {
    @GetMapping("/a")
    @ApiOperation("这是一个测试方法")
    @ApiImplicitParam(name = "a" ,value = "传入的参数",dataType = "String")
    public ApiResult<TestVO> test(String a,@RequestBody TestVO testVO){
        System.out.println(a);
        return ApiResult.ok(testVO);
    }
}

进入Swagger UI 界面http://localhost:端口号/swagger-ui.html#