Swagger

养匹小马

已于 2023-07-03 00:41:05 修改

阅读量74

点赞数

分类专栏： Java 后端文章标签： java

于 2023-07-03 00:32:19 首次发布

本文链接：https://blog.csdn.net/Chinaguo9873/article/details/131507487

版权

Java 同时被 2 个专栏收录

8 篇文章 0 订阅

订阅专栏

后端

8 篇文章 0 订阅

订阅专栏

Swagger

1.前后端分离时代

后端团队：后端控制层、服务层、数据访问层

前端团队：前端控制层、视图层

前后端通过API进行交互

前后端分离的项目相对更加独立，松耦合，甚至可以部署在不同的服务器上

2.Swagger简介

①号称世界上最流行的API框架

②RestFul API文档在线生成工具，API文档与API定义同步更新

③直接运行，可以在线测试API接口

④Swagger需要两个Jar包，分别为SpringFox-Swagger2和SpringFox-Swagger2-UI

⑤可以通过伪数据进行在线测试，类似于Postman

//仓库:https://central.sonatype.com/
<dependency>
    <groupId>org.thingsboard</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.4</version>
</dependency>

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

3.Spring Boot集成Swagger

步骤操作：

①新建Spring Boot项目

②测试项目是否搭建成功，新建一个请求

@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

③运行项目，访问http://localhost:8080/hello，返回hello即搭建成功

④添加Swagger的两个依赖

⑤集成Swagger2，添加SwaggerConfig

 @Configuration   //相当于@Component,将此类添加到配置中
 @EnableSwagger2 //开启SWagger2
public class SwaggerConfig {

}

⑥测试运行Swagger：访问http://localhost:8081/swagger-ui.html

4.版本冲突问题解决

步骤一: 降低SpringBoot、Swageer版本

<parent>
  <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
     <version>2.5.6</version>
   <relativePath/>

<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>

步骤二: 添加资源注册器，原因SpringBoot不会自动注册Swagger-ui.html

//重写静态资源映射方法,然后重启项目
@Configuration
    public class InterceptorConfig implements WebMvcConfigurer {  
        //注册资源映射器    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/**").addResourceLocations(
                    "classpath:/static/");
            registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                    "classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations(
                    "classpath:/META-INF/resources/webjars/");
        }
    }

5.配置Swagger

5.1 配置Swagger的Docker实例

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    //配置Swagger的Docker实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
}

5.2 配置Swagger-ui的apiInfo信息

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    //配置Swagger的Docker实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置Swagger的apiInfo信息
    public ApiInfo apiInfo(){
        Contact DEFAULT_CONTACT = new Contact("小郭", "", "");
        return new ApiInfo(
                "小郭的Api文档",
                "Api Documentation",
                "1.0",
                "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

5.3 配置扫描接口信息

Swagger只有一个Docker实例，其中**Docker.select( )通过配合buid( )**提供了扫描接口的配置方式，即select( )和buid( )必须配合使用

  @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描全部
                .apis(RequestHandlerSelectors.any())
                //不进行扫描
                .apis(RequestHandlerSelectors.none())
                //扫描指定包
                .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
                //扫描指定类的注解,参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.withClassAnnotation(GetMapping.class))
                //扫描指定方法的注解
                .apis(RequestHandlerSelectors.withMethodAnnotation(GwtCompatible.class))
                //过滤全部
                .paths(PathSelectors.any())
                //不过滤
                .paths(PathSelectors.none())
                //路径过滤
                .paths(PathSelectors.ant("/example/demo2/config/**"))
                //正则表达式过滤
                .paths(PathSelectors.regex(""))
                .build();
    }

5.4 配置是否启动Swagger

@Bean
public Docket docket(){
    return  new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //是否启动Swagger,默认为true
            .enable(false)
            //扫描接口设置
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
            .build();
}

5.5 Swagger根据环境自定义启动

通过外部判断当前环境，在开发环境中使用Swagger，生产环境中自动关闭

①添加生产环境，application-dev.properties并将开发环境切换为生产环境

spring.profiles.active = dev
server.port = 8081

②添加正式环境，application-pro.properties

server.port = 8082

③进行环境判断

@Bean
		//Environment用于读取环境配置properties信息
public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "pro");
        //通过environment.acceptsProfiles判断当前所处环境
        boolean flag = environment.acceptsProfiles(profiles);
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
                .build();
 }

5.6 配置API文档的分组

.groupName("xiaoguo")

5.7 配置多人分组

设置多个Docker实例即可

//默认配置为全部扫描
@Bean
public Docket docketThird(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("xiaoguo3");
 } 
@Bean
public Docket docketSencond(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("xiaoguo2");
}

5.8 配置实体类

一、实体类

//用于给实体类添加文档注释
@ApiModel("用户实体类")
public class User {
	//用于字段添加文档注释
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

二、扫描实体类

@RestController
public class HelloController {
    @GetMapping("User")
    //用于给方法添加文档注释
    @ApiOperation("用户控制类")
    //只要接口中返回值存在实体类,就会被Swagger扫描到
    public User user(){
        return new User();
    }
}