SpringBoot --- Swagger

2023-12-24 21:49:40

Swagger

1. 简介

号称世界上最流行的api框架
RestFul Api文档在线自动生成工具
直接运行，可以在线测试api接口
支持多种语言（java，php）

在项目中使用Swagger需要Springbox：

Swagger2
ui

2. Springboot整合Swagger

导入依赖

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

配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

测试运行

3. 配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    //配置了Swagger2的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    
    //配置Swagger信息=apiinfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("冉海锋","https://www.baidu.com/","448191580@qq.com");
        return new ApiInfo("狂神的SwaggerAPI文档",
                "即使再小的帆也能远航",
                "v1.0",
                "https://www.baidu.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

4. 配置扫描接口及开关

配置扫描接口

public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors 配置要扫描接口的方式
            //basePackage 指定要扫描的包
            //any() 扫描全部
            //none() 都不扫描
            //withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
            //withMethodAnnotation() 扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            //pahts() 过滤什么路径
            .paths(PathSelectors.ant("/kuang/**"))
            .build();
}

配置是否启动Swagger

.apiInfo(apiInfo())
.enable(false) //是否启用Swagger 如果为false 则Swagger不能在浏览器中访问
.select()

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

判断是不是生产环境 flag = flase 然后注入enable（flag ）

@Bean
public Docket docket(Environment environment){

    //设置要显示的Swagger环境
    Profiles profiles=Profiles.of("dev","test");

    //通过environment.acceptsProfiles判断是否处在自己设定的环境中
    boolean flag = environment.acceptsProfiles(profiles);


    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())

            .enable(flag) //是否启用Swagger 如果为false 则Swagger不能在浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))

            //.paths(PathSelectors.ant("/kuang/**"))
            .build();
}

5. 配置Api文档的分组

```
.groupName("冉海锋")
```

如何配置多个分组？多个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");
}

6. 实体类配置

编写实体类

@ApiModel("用户实体类")  //注解
public class User {
    @ApiModelProperty("用户名")   //注解
    public String username;
    @ApiModelProperty("密码")		//注解
    public String password; 	//注意：private访问不到的
}

Controller

//只要我们的接口中返回值中存在实体类 她就会被扫描到包
@RequestMapping("/user")
public User user(){
    return new User();
}

7. 注释

//放在方法上的
@ApiOperation("hello控制类")
@RequestMapping("/hello2")
public String hello(@ApiParam("用户名") String username){
    return "hello"+username;
}

程序可以测试！

8. 总结

我们可以通过Swagger给一些比较难理解的属性和接口增加注释信息
接口文档实时更新
可以在线测试，报错信息很明确！

Swagger是一个优秀的工具，几乎所有大公司都在使用它！

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

码农公寓