一、Swagger简介

Swagger是一套开源工具和规范，用于设计、构建和文档化RESTful Web服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。

• 官网：https://swagger.io/

二、SpringBoot集成Swagger

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

1. 新建一个SpringBoot-web项目

2. 添加Maven依赖

   
      io.springfox
      springfox-swagger2
      2.9.2
   
   
      io.springfox
      springfox-swagger-ui
      2.9.2
   
   

3. 编写HelloController，测试确保运行成功！

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

4. 要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger

    package com.liming.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2// 开启Swagger2的自动配置
    public class SwaggerConfig extends WebMvcConfigurationSupport {
    
        /**
         * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
         * @param registry void
         */
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 解决静态资源无法访问
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            // 解决swagger无法访问
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决swagger的js文件无法访问
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
   

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

   

三、配置Swagger

1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

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

2. 可以通过apiInfo()属性配置文档信息

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
                .build();
    }
   

3. Docket 实例关联上 apiInfo()

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
   

4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

   

四、配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口。

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .build();
   }
   

2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

   

3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

   1、basePackage(final String basePackage) // 根据包路径扫描接口

   2、any() // 扫描所有，项目中的所有接口都会被扫描到

   3、none() // 不扫描接口

   4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求

   withMethodAnnotation(final Class annotation)

   5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

   withClassAnnotation(final Class annotation)

4. 除此之外，我们还可以配置接口扫描过滤：

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
          // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   

5. 这里的可选值还有

   any() // 任何请求都扫描

   none() // 任何请求都不扫描

   regex(final String pathRegex) // 通过正则表达式控制

   ant(final String antPattern) // 通过ant()控制

SwaggerConfig基础配置全代码

package com.liming.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.limjing.controller")) // 只扫描controller接口
                .paths(PathSelectors.any()) // 配置如何通过path过滤,即这里扫描所有请求的接口
                .build();
    }
    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
                .build();
    }
    /**
     * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
     *
     * @param registry void
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

五、配置Swagger开关

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

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
         .select()
         .apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller"))
         .paths(PathSelectors.ant("/ss/**"))
         .build();
   }
   

   

2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

   @Bean
   public Docket docket(Environment environment) {
      // 设置要显示swagger的环境
      Profiles of = Profiles.of("dev", "test");
      // 判断当前是否处于该环境
      // 通过 enable() 接收此参数判断是否要显示
      boolean flag = environment.acceptsProfiles(of);
      
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(flag)
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   

3. 可以在项目中增加配置文件

   application.yml ->spring.profiles.active=dev

   application-dev.yml ->端口：8081

   application-pro.yml->端口：8082

   结果：pro正式环境会关闭swagger功能

六、配置API分组

1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

   @Bean
   public Docket docket(Environment environment) {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
         .groupName("黎明") // 配置分组
          // 省略配置....
   }
   

2. 重启项目查看分组

   

3. 如何配置多个分组？配置多个分组只需要配置多个docket即可：

   @Bean
   public Docket docket1(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
   }
   @Bean
   public Docket docket2(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
   }
   @Bean
   public Docket docket3(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
   }
   

4. 重启项目查看即可

   

七、实体配置

1. 新建一个实体类

   //@Api("注释")
   @ApiModel("用户实体")
   public class User {
       @ApiModelProperty("用户名")
       private String username;
       @ApiModelProperty("密码")
       private String password;
       public String getUsername() {
           return username;
       }
       public void setUsername(String username) {
           this.username = username;
       }
       public String getPassword() {
           return password;
       }
       public void setPassword(String password) {
           this.password = password;
       }
   }
   

2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

   @RestController
   public class HelloController {
       //   /error默认错误请求
       @GetMapping("/hello")
       public String hello() {
           return "hello";
       }
       //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
       @PostMapping("/user")
       public User user() {
           return new User();
       }
   }
   

3. 重启查看测试

   

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.

• @ApiModel为类添加注释

• @ApiModelProperty为类属性添加注释

  【注意点】：在正式发布的时候，关闭Swagger！！！

  常用注解

  Swagger的所有注解定义在io.swagger.annotations包下

  下面列一些经常用到的，未列举出来的可以另行查阅说明：

  Swagger注解	简单说明
  @Api(tags = “xxxController说明”)	作用在接口类上
  @ApiOperation(“xxx接口说明”)	作用在接口方法上
  @ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
  @ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
  @ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty
  @ApiImplicitParam()	用于描述API接口的参数信息(常用的属性包括：name：参数名,value：参数的描述信息,paramType：参数的类型，可以是path、query、body、header、form等,dataType：参数的数据类型,required：参数是否必需，布尔值，默认为false,defaultValue：参数的默认值

  我们也可以给请求的接口配置一些注释

  1. 在HelloController控制类中的接口添加api接口注释

     @RestController
     public class HelloController {
         ......
         @ApiOperation("Hello控制接口")
         @GetMapping("/hello")
         public String hello2(@ApiParam("用户名") String username) {
             return "hello" + username;
         }
         
         @ApiOperation("get测试")
         @GetMapping("/get")
         public User hello2(@ApiParam("用户") User user) {
             return user;
         }
         
      	@GetMapping("/users/{id}")
      	@ApiOperation(value = "获取用户详情")
      	@ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", dataType = "Long", required = true)
      	public User getUserById(@PathVariable("id") Long id) {
      	    // 获取用户详情的业务逻辑
      	}
      	@GetMapping("/users")
      	@ApiOperation(value = "获取用户列表")
      	@ApiImplicitParams({
      	    @ApiImplicitParam(name = "page", value = "页码", paramType = "query", dataType = "int", defaultValue = "1"),
      	    @ApiImplicitParam(name = "size", value = "每页数量", paramType = "query", dataType = "int", defaultValue = "10")
      	})
      	public List getUsers(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "10") int size) {
      	    // 获取用户列表的业务逻辑
      	}
     }
     

     

  2. 进行try it out测试

     

     测试结果

     

  拓展：其他皮肤

  我们可以导入不同的包实现不同的皮肤定义：

  1、默认的 访问 http://localhost:8080/swagger-ui.html

   
     io.springfox
     springfox-swagger-ui
     2.9.2
  
  

  

  2、bootstrap-ui 访问 http://localhost:8080/doc.html

  
  
  
     com.github.xiaoymin
     swagger-bootstrap-ui
     1.9.1
  
  

  

  八.微服务使用Knife4j

  官网地址:https://doc.xiaominfo.com/

  

  第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：

  
      com.github.xiaoymin
      knife4j-openapi2-spring-boot-starter
      4.3.0
  
  

  第二步：配置yml属性，代码如下：

  knife4j:
    enable: true #表示启用Knife4j，允许API文档生成和展示
    openapi: #表示配置OpenAPI相关的信息
      title: Knife4j官方文档 #设置了API文档的标题
      description: "`我是测试`,**你知道吗** #设置了API文档的描述
      email: 2356731504@qq.com #电子邮件地址
      concat: 黎明 #联系人的名称
      version: v1.0 
      license: Apache 2.0 #API使用的许可证为"Apache 2.0"
      license-url: https://stackoverflow.com/ #提供了许可证的URL链接
      terms-of-service-url: https://stackoverflow.com/ #提供了服务条款的URL链接
      group: #分组信息
        default:
          group-name: default #分组名称
          api-rule: package #按照包来进行API的分组
          api-rule-resources: #指定了API规则的资源信息
            - com.liming.controller
  

  第三步:新建一个接口Controller类，如下：

  @Api(tags = "首页模块")
  @RestController
  public class IndexController {
      @ApiImplicitParam(name = "name",value = "姓名",required = true)
      @ApiOperation(value = "向客人问好")
      @GetMapping("/sayHi")
      public ResponseEntity sayHi(@RequestParam(value = "name")String name){
          return ResponseEntity.ok("Hi:"+name);
      }
  }
  

  万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果

  http://ip:端口/doc.html

   
   网站设计制作  深圳外贸网站建设  设计师网络接单  网络营销专员的就业前景  外贸企业网站怎么制作  福州网站制作维护