swagger-springboot

时间：2022-11-14 15:00:01 温度传感器wkl

文章目录

1：什么是swagger
2:swagger-ui 和 springfox-swagger-ui
3：springboot使用swagger
- 1：导包
- 2：编写swagger配置类
- 3：配置API文档信息
- 4：配置swagger扫描的包
- 5:配置接口扫描过滤器
- 6:配置是否启动Swagger
- 7:配置API分组
4：Controller提示信息配置
- 1：@API提示整个controller的信息
- 2：@ApiOperation具体方法配置
5:提示使用中的实体类
6：swagger的详细注解

1：什么是swagger

Swagger 是一款RESTFUL在线自动生成接口文档功能测试功能软件；
Swagger的目标是为REST APIs 定义与语言无关的标准接口，使人和计算机在看不到源代码或文档或通过网络流量检测时能够找到和理解各种服务的功能。当服务通过Swagger定义，消费者可以通过少量的逻辑与远程服务互动。类似于低级编程接口，Swagger在调用服务时删除了很多猜测。

2:swagger-ui 和 springfox-swagger-ui

Swagger Spec 是规范。
Swagger Api 是 Swagger Spec 规范它支持实现 jax-rs, restlet, jersey 等等。
Springfox libraries 是 Swagger Spec 规范另一个实现侧重于 spring 生态系统。
Swagger.js and Swagger-ui 是 javascript 客户端库，可以消费这个规范。
springfox-swagger-ui 以方便的方式包装 swagger-ui ，使得 Spring 可提供服务。
总的来说：

Swagger 是一种规范。
springfox-swagger 是基于 Spring 实现生态系统规范。
springfox-swagger-ui 是对 swagger-ui 可以使用的封装 Spring 的服务。

3：springboot使用swagger

1：导包

<dependency>     <groupId>io.springfoxgroupId>     <artifactId>springfox-swagger2artifactId>     <version>2.9.2version> dependency> <dependency>     <groupId>io.springfoxgroupId>     <artifactId>springfox-swagger-uiartifactId>     <version>2.9.2version> dependency>

2：编写swagger配置类

package com.wkl.swaggerspringboot.config;  import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/** * Description: * Date: 2022/6/21 - 下午 11:54 * author: wangkanglu * version: V1.0 */
@Component
@EnableSwagger2  //开启Swagger2的自动配置
public class SwaggerConfig { 
        
    @Bean
    public Docket docket(){ 
        
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

上面的配置就已经可以使用Swagger了。通过访问http://localhost:8080/swagger-ui.html（自己的项目访问路径/swagger-ui.html）来访问接口文档就可以了。
我写了一个hellocontroller

3：配置API文档信息

通过apiInfo()属性配置文档信息：

package com.wkl.swaggerspringboot.config;

import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
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;

import java.util.ArrayList;

/** * Description: * Date: 2022/6/21 - 下午 11:54 * author: wangkanglu * version: V1.0 */
@Component
@EnableSwagger2  //开启Swagger2的自动配置
public class SwaggerConfig { 
        
    @Bean
    public Docket docket(){ 
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger-ui的api信息
    private ApiInfo apiInfo(){ 
        
        Contact contact = new Contact("联系人姓名","http://www.baidu.com/联系人连接","邮箱");
        return new ApiInfo("Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()); // 扩展
    }

}

4：配置swagger扫描的包

通过上述演示，可以看到系统内添加了默认的controller，那么我们如何配置swagger只扫描我们制定的哪些controller呢？
可以构建Docket时通过select()方法配置怎么扫描接口。

package com.wkl.swaggerspringboot.config;

import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
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;

import java.util.ArrayList;

/** * Description: * Date: 2022/6/21 - 下午 11:54 * author: wangkanglu * version: V1.0 */
@Component
@EnableSwagger2  //开启Swagger2的自动配置
public class SwaggerConfig { 
        
    @Bean
    public Docket docket(){ 
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller")).build();
    }

    //配置swagger-ui的api信息
    private ApiInfo apiInfo(){ 
        
        Contact contact = new Contact("联系人姓名","http://www.baidu.com/联系人连接","邮箱");
        return new ApiInfo("Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()); // 扩展
    }

}

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

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
withMethodAnnotation(final Class<? extends Annotation> annotation)// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withClassAnnotation(final Class<? extends Annotation> annotation) // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
basePackage(final String basePackage) // 根据包路径扫描接口

5：配置接口扫描过滤

上述方式可以通过具体的类、方法等扫描接口，还可以配置如何通过请求路径配置：
例如，我有两个controller，一个是hello/,一个是user/,如下：

配置扫描过滤

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

结果如下；

这里的可选值还有：

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制，返回true扫描，false不扫描
ant(final String antPattern) // 通过ant()表达式控制，返回true扫描，false不扫描

6：配置是否启动Swagger

我们可以通过yml的配置文件，在测试环境中才开启swagger，在正式环境中关闭swagger

@Bean
    public Docket docket(Environment environment){ 
        

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .enable(b)
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
                // 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
                .paths(PathSelectors.ant("/user/**"))
                .build();
    }

正式环境就会提示这个

7:配置API分组

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

@Bean
    public Docket docket(Environment environment){ 
        

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .enable(b)
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
                // 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
                .paths(PathSelectors.ant("/user/**"))
                .build()
                .groupName("test");
    }

那么如何配置多个分组呢？只需要配置多个docket即可；

@Bean
    public Docket docketHello(Environment environment){ 
        

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .enable(b)
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
                // 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
                .paths(PathSelectors.ant("/hello/**"))
                .build()
                .groupName("hello");
    }

    @Bean
    public Docket docketUser(Environment environment){ 
        

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .enable(b)
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.wkl.swaggerspringboot.controller"))
                // 配置如何通过 path过滤 即这里只扫描 请求以 /user开头的接口
                .paths(PathSelectors.ant("/user/**"))
                .build()
                .groupName("user");
    }

4：Controller提示信息配置

从上述配置中我们可以看到，虽然实现了我们swagger的功能，但是提示却非常不友好，设置到user-controller是干嘛的呢？对此我们可以通过@Api来进行友好提示

1：@API提示整个controller的信息

package com.wkl.swaggerspringboot.controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;

/** * Description: * Date: 2022/6/21 - 下午 11:57 * author: wangkanglu * version: V1.0 */
@RestController
@RequestMapping("/user")
@Api(value = "人员user相关操作value",tags = "人员user相关操作tags")
public class UserController { 
        
    @PostMapping("test1")
    public String test1(@RequestParam String str){ 
        
        return "usertest1";
    }


}

2：@ApiOperation配置在具体方法上

package com.wkl.swaggerspringboot.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;

/** * Description: * Date: 2022/6/21 - 下午 11:57 * author: wangkanglu * version: V1.0 */
@RestController
@RequestMapping("/user")
@Api(value = "人员user相关操作value",tags = "人员user相关操作tags")
public class UserController { 
        
    @PostMapping("test1")
    @ApiOperation("写的一个user的测试方法")
    public String test1(@RequestParam String str){ 
        
        return "usertest1";
    }


}

5：对使用中的实体类进行提示

实体类配置；

@Data
@ApiModel(value = "人员信息", description = "人员信息对象")
public class User { 
        
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;

}

controller中用实体类作为参数

 @PostMapping("test2")
    @ApiOperation("参数为user实体类的测试方法")
    public String test2(@RequestBody User user){ 
        
        return "usertest2";
    }

就可以在使用时除了会传入默认值外，还会有实体属性的友好提示

6：swagger的详细注解

https://blog.csdn.net/xiaojin21cen/article/details/78654652
https://blog.csdn.net/qq_34823218/article/details/121790150

锐单商城拥有海量元器件数据手册、IC替代型号，打造电子元器件IC百科大全！

swagger-springboot

文章目录

相关文章