Swagger学习与使用

最新推荐文章于 2024-04-28 15:26:14 发布

程序员老周666

最新推荐文章于 2024-04-28 15:26:14 发布

阅读量93

点赞数

本文链接：https://blog.csdn.net/zhouwenxing666/article/details/131200242

版权

java 同时被 2 个专栏收录

17 篇文章 0 订阅

订阅专栏

swagger

1 篇文章 0 订阅

订阅专栏

Swagger

学习目标：

了解Swagger作用与概念
了解前后端分离
在SpringBoot中集成Swagger

前后端如何交互？ ===》API

前后端相对独立，松耦合，前后端可以部署在不同的服务器上

产生一个问题：前后端集成联调，前后端人员无法做到”“及时协商，尽早解决”，最终导致问题集中爆发

解决方案：

首先置顶一个schema(计划提纲)，实时更新最新API(如后端改变了，前端第一时间就知道改变了)，降低集成风险
早些年：制定word计划文档；
前后端分离：
- 前端测试后端接口：postman（早些年，使用第三方工具postman）
- 后端提供接口，需要实时更新最新的改动

Swagger 应运而生

RestFul Api 文档在线自动生成工具（一旦写完代码，Api文档自动更新）
直接运行，可以在线测试Api接口（Api接口就是controller 的@RequestMapping）
支持多种语言：Java，Php…

Swagger官网 https://swagger.io/

在项目中使用Swagger需要springbox(使用jar包)

swagger2
ui

SpringBoot集成Swagger

导入相关依赖

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

报错：

Error starting ApplicationContext. To display the conditions report re-run your application with ‘debug’ enabled.
2023-06-09 11:20:32.782 ERROR 21988 — [ main] o.s.boot.SpringApplication : Application run failed

org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

原因：springboot2.7.12与swagger2.9.2冲突

springboot2.7.12与swagger2.9.2冲突原因：Springfox 假设 Spring MVC 的路径匹配策略是 ant-path-matcher，而 Spring Boot 2.6.x版本的默认匹配策略是 path-pattern-matcher，这就造成了上面的报错。

解决办法：在application.properties 下添加spring.mvc.pathmatch.matching-strategy=ant_path_matcher （yaml按yaml格式来一样）

——————————————————————————————————————————————————————————————

接下来

在启动类同一级orconfig包下，写一个Swaggerconfig

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

访问：http://localhost:8080/swagger-ui.html

856aafad832760c2b3548b00138d27a

配置Swagger

为什么要配置swagger？因为swagger 部署spring的包，没有被spring自动配置，故需要配置

Swagger的bean实例

Swagger配置扫描接口

docket()，apiInfo() 均写在SwaggerConfig类里

  @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors-配置要扫描接口的方式;
                //.basePackage("包名")-指定要扫描的包
                //.any()-扫描全部
                //.none()-不扫描
                //.withClassAnnotation()-扫描类上的注解，参数是一个注解的反射对象
                //.withMethodAnnotation()-扫描方法上的注解
                //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//只会扫描带有@RestController的类
                //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.zhou.controller"))一般用这个
                //paths()-过滤什么路径
                //.paths(PathSelectors.ant("/zhou/**"))//过滤/zhou下面所有
                .build();//build工厂模式

    }

//配置Swagger信息 需要apiInfo 这个类
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("zwx", "https://blog.csdn.net/zhouwenxing666", "1804808430@qq.com");
        return new ApiInfo(
                "周文星的SwaggerAPI文档",
                "冲冲冲!",
                "v1.0",
                "https://blog.csdn.net/zhouwenxing666",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }

配置是否启动Swagger

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.enable()-是否启动Swagger,默认是true，但也可以在()里面加上false表示不启动Swagger
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhou.controller"))一般用这个
                .build();//build工厂模式

    }

我只希望我的Swagger在生产环境中使用，而在发布的时候不使用。该如何写

思路

判断是不是生产环境, 若是生产环境设标签flag=true，若不是设标签flag=false
注入enable(flag)

#application.properties
server.port=8081
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

spring.profiles.active=dev

#application-dev.properties
server.port=8082
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

#application-prod.properties
server.port=8083
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

SwaggerConfig类下的docket代码如下

@Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles(profiles) 判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);//如果监测到当前的环境是dev 或 test 则为true，否则为false
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhou.controller"))一般用这个
                .build();//build工厂模式

    }

配置API文档的分组

.groupName("htzw") //在下面代码里

@Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles(profiles) 判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);//如果监测到当前的环境是dev 或 test 则为true，否则为false

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("htzw")//配置API文档的分组为htzw
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhou.controller"))一般用这个
                .build();//build工厂模式

    }

如何配置多个分组？–写多个Docket实例

public class SwaggerConfig {

    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles(profiles) 判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);//如果监测到当前的环境是dev 或 test 则为true，否则为false
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("htzw")
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhou.controller"))一般用这个
                .build();//build工厂模式
    }

    @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信息 需要apiInfo 这个类
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("zwx", "https://blog.csdn.net/zhouwenxing666", "1804808430@qq.com");
        return new ApiInfo(
                "周文星的SwaggerAPI文档",
                "冲冲冲!",
                "v1.0",
                "https://blog.csdn.net/zhouwenxing666",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }

}

显示图片

实体类配置

@ApiModel("用户实体类")//在API文档中给类User加注释
public class User {
    @ApiModelProperty("用户名")//在API文档中给属性username加注释
    public String username;

    @ApiModelProperty("密码")//在API文档中给属性password加注释
    public String password;
}

controller

@RestController
public class HiController {

    @GetMapping(value = "/hi")
    @ApiOperation("hi方法")//给Api文档中hi方法加注释
    public String hi(){
        return "hello";
    }

    //只要我们的接口（Controller层的各种Mapping）中，返回值中存在实体类，该类就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    @ApiOperation("Post测试类")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user){
        return user;
    }

}

总结

1 可以通过Swagger给一些比较难理解的属性或接口添加注释信息

2 接口文档实时更新

3 在线测试接口

注意点：在正式发布的时候，关闭Swagger！！！出于安全考虑，且节省运行的内存

程序员老周666

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Swagger学习与使用

RestFul Api 文档在线自动生成工具（一旦写完代码，Api文档自动更新）直接运行，可以在线测试Api接口（Api接口就是controller 的@RequestMapping）支持多种语言：Java，Php…
复制链接

扫一扫