其他分享
首页 > 其他分享> > swagger2入门实例

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#
在这里插入图片描述
在这里插入图片描述

标签:return,String,ApiResult,swagger2,实例,参数,swagger,public,入门
来源: https://blog.csdn.net/m0_54797663/article/details/115284076