Swagger环境搭建及使用

最新推荐文章于 2024-10-10 22:15:00 发布

code@fzk

最新推荐文章于 2024-10-10 22:15:00 发布

阅读量620

点赞数 1

分类专栏： java组件文章标签： spring boot java intellij idea

本文链接：https://blog.csdn.net/qq_44002865/article/details/106021428

版权

java组件专栏收录该内容

5 篇文章 0 订阅

订阅专栏

Swagger环境搭建及使用

文章目录

Swagger环境搭建及使用
1、环境搭建
2、使用

1、环境搭建

第一步：创建SpringBoot项目并引入依赖

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

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

第二步：编写Controller类

@RestController  //Bean中的注解
public class controllerTest {

    //Get请求
    @GetMapping("fzkGet")
    public String fzkGet(){
        return "fzkGet";
    }

    //Post请求
    @PostMapping("fzkPost")
    public String fzkPost(){
        return "fzkPost";
    }

    //Put请求
    @PutMapping("fzkPut")
    public String fzkPut(){
        return "fzkPut";
    }

    //Delete请求
    @DeleteMapping("fzkDelete/{id}")
    public String fzkDelete(@PathVariable String id){
        return "fzkDelete";
    }
}

第三步：编写Swagger配置类并加入 @EnableSwagger2 注解

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
}

第四步：在主配置文件中添加注解扫描

Controller类和 Swagger类都在 com.itfzk 包下（com.itfzk包是自己定义的包）

@SpringBootApplication
@ComponentScan(basePackages = {"com.itfzk"})  //开启注解扫描
public class Test100Application {
    public static void main(String[] args) {
        SpringApplication.run(Test100Application.class, args);
    }

}

第五步：访问测试

地址： http://localhost:8080/swagger-ui.html (localhost:8080是自己的ip地址和端口号，swagger-ui.html是显示的页面)

效果图
在这里插入图片描述

2、使用

配置Swagger

1、Swagger实例Bean是Docket，通过配置Docket实例来配置Swaggger
2、通过apiInfo()属性配置文档信息

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {

    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")  //分组信息
                .apiInfo(webApiInfo());
    }

    //配置文档信息
    private ApiInfo webApiInfo(){
        //联系人信息
        Contact contact = new Contact("fzk", "https://blog.csdn.net/qq_44002865", "1820713352@qq.com");
        return new ApiInfo(
                "Swagger测试",  //标题
                "演示如何配置使用Swagger",  //描述
                "v1.0",  //版本
                "urn:tos",  //服务条件
                contact,  //联系人信息
                "Apache 2.0",  //许可
                "http://www.apache.org/licenses/LICENSE-2.0",  //许可链接
                new ArrayList<>());  //扩展
    }
}

测试效果
在这里插入图片描述

配置扫描接口

构建Docket时通过 select() 方法配置来扫描接口

apis()

使用方法
- .select().apis(RequestHandlerSelectors.[需要扫描的配置]).build();
- 需要扫描的配置:
  - basePackage(final String basePackage) ：根据包路径扫描接口
    - .select().apis(RequestHandlerSelectors.basePackage(“com.itfzk.controller”)).build();
      - 扫描 com.itfzk.controller 包
  - any() ：扫描所有，项目中的所有接口都会被扫描到
    - .select().apis(RequestHandlerSelectors.any()).build();
      - 扫描所有
  - none() ：不扫描接口
    - .select().apis(RequestHandlerSelectors.none()).build();
      - 不扫描
  - withMethodAnnotation(final Class<? extends Annotation> annotation) ：通过方法上的注解扫描
    - .select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)).build();
      - 只扫描get请求
  - withClassAnnotation(final Class<? extends Annotation> annotation) ：通过类上的注解扫描
    - .select().apis(RequestHandlerSelectors.withClassAnnotation(Controller.class)).build();
      - 只扫描有Controller注解的类中的接口

举例

@Bean  //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(webApiInfo())
        .select()  // 通过.select()方法，配置扫描接口,RequestHandlerSelectors配置扫描接口
        .apis(RequestHandlerSelectors.basePackage("com.itfzk.test100.controller")).build();
}

paths()

使用方法
- .select().paths(PathSelectors.[需要扫描的配置]).build();
- 需要扫描的配置:
  - any() ：任何请求都扫描
  - none() ：任何请求都不扫描
  - regex(final String pathRegex) ：通过正则表达式控制
  - ant(final String antPattern) ：通过ant()控制

举例

@Bean  //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(webApiInfo())
        .select().paths(PathSelectors.ant("/fzk/**")).build();
}

配置Swagger开关

通过 enable() 方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

开发和测试的时候开启，项目运行时就不启动

测试不启用 Swagger

@Bean  //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(webApiInfo())
        .enable(false);  //是否启用swagger，不启用
}

测试结果

配置API分组

如果没有配置分组，默认是default

通过 groupName() 方法即可配置分组

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
    
    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")  //配置分组 
                .apiInfo(webApiInfo());
    }
}

配置多个分组只需要配置多个docket

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
    
    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk")
                .apiInfo(webApiInfo());
    }
    

    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk1")
                .apiInfo(webApiInfo1());
    }


    @Bean  //配置docket以配置Swagger具体参数
    public Docket webApiConfig2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("fzk2")
                .apiInfo(webApiInfo2());
    }
}

常用注解

@Api()

用于 Controller 类上；表示标识这个类是swagger的资源
- tags ：表示说明
- value ：也是说明，可以使用tags替代
```
@RestController
@Api(tags = "测试Swagger")
public class controllerTest {
}
```

在这里插入图片描述

@ApiOperation()

用于Controller方法；表示一个http请求的操作

value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

@RestController
@Api(tags = "测试Swagger")
public class controllerTest {

    @ApiOperation("查询Swagger")
    @GetMapping("/find")
    public String find() {
        return "Swagger";
    }
}

在这里插入图片描述

@ApiParam()

用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

name ：参数名
value ：参数说明
required ：是否必填

@RestController
@Api(tags = "测试Swagger")
public class controllerTest {

    @ApiOperation("查询Swagger")
    @PostMapping("/findById")
    public String find(@ApiParam(name = "id", value = "用户id", required = true) String id) {
        return "Swagger";
    }
}

在这里插入图片描述

@ApiModel() & @ApiModelProperty()

@ApiModel()
- 用于类；表示对类进行说明，用于参数用实体类接收
  - value–表示对象名
  - description–描述
  - 都可省略

@ApiModelProperty()

用于方法，字段；表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏

@Data
@ApiModel(value = "User对象", description = "用户")
public class User {
    @ApiModelProperty(value = "用户名")
    private String userName;

    @ApiModelProperty(value = "密码")
    private String password;
}