Swagger学习与使用

Swagger

Swagger简介

  • 号称世界上最流行的Api框架
  • RestFul Api文档在线自动测试生成工具=》Api文档与Api定义同步更新
  • 直接运行，可以在线测试Api接口
  • 支持多种语言：（java，Php....）

官网：https://swagger.io/

在项目中使用Swagger需要springfox；

  • swagger2
  • ui

Springboot集成Swagger

  1. 新建一个Springboot项目

  2. 导入相关依赖

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

  3. 编写一个hello工程

  4. 配置Swagger ==》config

    @Configuration
@EnableSwagger2    //开启Swagger2
public class SwaggerConfig {


}

    出现问题：

    Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
2022-10-10 21:01:59.416 ERROR 4016 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.23.jar:5.3.23]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_121]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:147) ~[spring-boot-2.7.4.jar:2.7.4]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:734) [spring-boot-2.7.4.jar:2.7.4]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:408) [spring-boot-2.7.4.jar:2.7.4]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:308) [spring-boot-2.7.4.jar:2.7.4]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306) [spring-boot-2.7.4.jar:2.7.4]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1295) [spring-boot-2.7.4.jar:2.7.4]
	at com.dong.swagger.SwaggerDemoApplication.main(SwaggerDemoApplication.java:10) [classes/:na]
Caused by: java.lang.NullPointerException: null
	at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWrapper.java:56) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
	at springfox.documentation.RequestHandler.sortedPaths(RequestHandler.java:113) ~[springfox-core-3.0.0.jar:3.0.0]
	at springfox.documentation.spi.service.contexts.Orderings.lambda$byPatternsCondition$3(Orderings.java:89) ~[springfox-spi-3.0.0.jar:3.0.0]
	at java.util.Comparator.lambda$comparing$77a9974f$1(Comparator.java:469) ~[na:1.8.0_121]
	at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_121]
	at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_121]
	at java.util.Arrays.sort(Arrays.java:1512) ~[na:1.8.0_121]
	at java.util.ArrayList.sort(ArrayList.java:1454) ~[na:1.8.0_121]
	at java.util.stream.SortedOps$RefSortingSink.end(SortedOps.java:387) ~[na:1.8.0_121]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_121]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_121]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_121]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:482) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471) ~[na:1.8.0_121]
	at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234) ~[na:1.8.0_121]
	at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499) ~[na:1.8.0_121]
	at springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider.requestHandlers(WebMvcRequestHandlerProvider.java:81) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
	at java.util.stream.ReferencePipeline$3$1.accept(ReferencePipeline.java:193) ~[na:1.8.0_121]
	at java.util.ArrayList$ArrayListSpliterator.forEachRemaining(ArrayList.java:1374) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:481) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471) ~[na:1.8.0_121]
	at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708) ~[na:1.8.0_121]
	at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234) ~[na:1.8.0_121]
	at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499) ~[na:1.8.0_121]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.withDefaults(AbstractDocumentationPluginsBootstrapper.java:107) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.buildContext(AbstractDocumentationPluginsBootstrapper.java:91) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.bootstrapDocumentationPlugins(AbstractDocumentationPluginsBootstrapper.java:82) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:100) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:178) ~[spring-context-5.3.23.jar:5.3.23]
	... 14 common frames omitted


Process finished with exit code 1

    问题原因：

    因为Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。

    解决方法：

    1. 降低springboot版本

    2. application.yml 或applicaiton.properties 中添加如下配置

      spring.mvc.pathmatch.matching-strategy=ant_path_matcher

      参考文档：https://blog.csdn.net/hadues/article/details/123753888

  5. 测试运行 http://localhost:8080/swagger-ui.html

    ​

配置Swagger

@Configuration
@EnableSwagger2    //开启Swagger2
public class SwaggerConfig {

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

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("Mr.Dong", "https://www.cnblogs.com/No2Asylum/", "867875119@qq.com");


        return new ApiInfo(
                "Mr.Dong的SwaggerAPI文档",
                "初试swaggerAPI",
                "V1.0",
                "https://www.cnblogs.com/No2Asylum/",
                 DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList());
    }
    }

Swagger配置扫描接口

Docket.select()

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage()   指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation   扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation  扫描方法上的注解

                .apis(RequestHandlerSelectors.basePackage("com.dong.swagger.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.ant("/dong/**"))
                .build();
    }

配置是否启动Swagger

 //配置Swagger的Docker的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            
                //enable()      是否启动Swagger ，如果为false，则swagger不能在浏览器中访问
                .enable(true)
                .select()
                
                .apis(RequestHandlerSelectors.basePackage("com.dong.swagger.controller"))
                //paths()过滤什么路径
                //.paths(PathSelectors.ant("/dong/**"))
                .build();
    }

我只希望在我的Swagger在生产环境中使用，在发布环境中不使用？

  • 判断是不是生产环境 flag=false
  • 注入enable(flag)
 @Bean
    public Docket docket(Environment environment){


        //设置要显示的环境
        Profiles profiles = Profiles.of("dev","test");
        //获取nvironment.acceptsProfiles(profiles)判断是否处在自己设定的环境：
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable()      是否启动Swagger ，如果为false，则swagger不能在浏览器中访问
                .enable(flag)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage()   指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation   扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation  扫描方法上的注解

                .apis(RequestHandlerSelectors.basePackage("com.dong.swagger.controller"))
                //paths()过滤什么路径
                //.paths(PathSelectors.ant("/dong/**"))
                .build();
    }

配置API文档的分组

如何配置多个分组：多个Docket实例

	@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类配置

只要我们的接口中，返回值存在实体类，他就会被扫描到Swagger中

//@Api(注释)
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

控制层配置

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping(value = "/user")
    public User getUser(){
        return new User();
    }

    //Operation接口,不是放在类上的，是放在方法上的
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }


    @ApiOperation("Post测试类")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户") User user){
        return user;
    }

}

总结

  1. 接口文档实时更新
  2. 可以在线测试
  3. 我们可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
  4. 打开Swagger调试页面的网址 http://localhost:8080/swagger-ui.html
posted @   No2_Asylum  阅读(5)  评论(0)  编辑  收藏  举报
（评论功能已被禁用）
相关博文：
· swagger
· Swagger-学习
· 【学习笔记】Swagger
· Swagger入门通俗易懂
· swagger的使用
阅读排行：
· DeepSeek 开源周回顾「GitHub 热点速览」
· 记一次.NET内存居高不下排查解决与启示
· 物流快递公司核心技术能力-地址解析分单基础技术分享
· .NET 10首个预览版发布：重大改进与新特性概览！
· .NET10 - 预览版1新功能体验（一）
点击右上角即可分享
微信分享提示
AI FOR CODE 大赛