spring-boot之接口文档Swagger配置使用

Swagger

前后端分离
Vue + SpringBoot
后端时代:前端只用管理静态页面; html==> 后端。模板引擎JSP =>后端是主力
前后端分离式时代:
●后端:后端控制层，服务层,数据访问层[后端团队]
●前端:前端控制层，视图层[前端团队]
。伪造后端数据，json。 已经存在了，不需要后端，前端工程依旧能够跑起来
●前端后如何交互? ===> API
●前后端相对独立，松耦合;
●前后端甚至可以部署在不同的服务器上;
I

官网https://swagger.io/

在项目使用Swagger需要springbox;
●swagger2
●ui

SpringBoot集成Swagger

1,新建一个springboot-web项目

2,导入maven

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

1
2
3
4
5
6
7

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
1
2
3
4
5
6

spring boot老版本使用以上配置

或者

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
1
2
3
4
5
6

3.编写一-个Hello工程
4.配置Swagger ==> Config

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableOpenApi
public class SwaggerConfig {
}
1
2
3
4
5
6
7
8
9

访问地址http://localhost:8080/swagger-ui/

使用swagger3出现Failed to start
bean‘documentationPluginsBootstrapper 错误，还可以在application.properties里面加"spring.mvc.pathmatch.matching-strategy= ANT_PATH_MATCHER"

配置Swagger信息

默认调用的是ApiInfo里面的

this.apiInfo = ApiInfo.DEFAULT;

public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
1

static {
    DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
1
2
3

@Configuration
@EnableOpenApi
public class SwaggerConfig {


    //配置了Swagger的Docker的bean实例,替换默认值  this.apiInfo = ApiInfo.DEFAULT;
    
   /* static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }*/
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());
    }

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("陈平安", "urn:tos", "2188671488.com");
        return new ApiInfo("陈平安的Swagger API文档",
                "有不开心，也有在努力生活",
                "1.0",
                "urn:tos",
                contact,
               /* DEFAULT_CONTACT,*/
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Swagger配置扫描接口

Docket.select()

@Bean
public Docket docket(){

    return new Docket(DocumentationType.OAS_30).
            apiInfo(apiInfo()).
            select()
            //requestHandler ->
                    //RequestHandlerSelectors 配置要扫描接口的方式
                            //basePackage("")指定扫描的包
                            //any()扫描全部
                            //none()都不扫描
                            //withClassAnnotation 扫描类上的注解 withClassAnnotation.(RestController.class)
                            //withMethodAnnotation 扫描方法上的注解 withMethodAnnotation.(GetMapping.class)
           .
             apis(RequestHandlerSelectors.basePackage("com.controller")).
    //过滤什么路径
            paths(PathSelectors.ant("/com/**")).
            build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

配置是否启动swagger

@Bean
public Docket docket(){

    return new Docket(DocumentationType.OAS_30).
            apiInfo(apiInfo()).
            enable(true).//enable是否启动swagger, 如果为False, 则swagger不能再浏览器中访问
                    select()
            //requestHandler ->
                    //RequestHandlerSelectors 配置要扫描接口的方式
                            //basePackage("")指定扫描的包
                            //any()扫描全部
                            //none()都不扫描
                            //withClassAnnotation 扫描类上的注解 withClassAnnotation.(RestController.class)
                            //withMethodAnnotation 扫描方法上的注解 withMethodAnnotation.(GetMapping.class)
           .
             apis(RequestHandlerSelectors.basePackage("com.controller")).
    //过滤什么路径
            //paths(PathSelectors.ant("/com/**")).
            build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

●判断是不是生产环境flag = false
●注入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.OAS_30).
            apiInfo(apiInfo()).
            //enable(true).//enable是否启动swagger, 如果为False, 则swagger不能再浏览器中访问
            enable(flag).
                    select()
           .apis(RequestHandlerSelectors.basePackage("com.controller")).
            build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

application.properties

spring.profiles.active=dev
1

applicationdev.properties

server.port=8081
1

配置API文档分组

groupName("陈平安")
1

配置多个分组:多个Docket实例既可

@Bean
public Docket docket1(){
    return  new Docket(DocumentationType.OAS_30).groupName("A");
}
@Bean
public Docket docket2(){
    return  new Docket(DocumentationType.OAS_30).groupName("B");
}
@Bean
public Docket docket3(){
    return  new Docket(DocumentationType.OAS_30).groupName("C");
}
1
2
3
4
5
6
7
8
9
10
11
12

实体类配置

@Api(tags = “”)

类注释

@ApiModel(“”)

方法注释

@ApiOperatio

//@Api(注释)
@ApiModel("用户类")
public class User {

    @ApiModelProperty("用户名")
    public  String username;
    @ApiModelProperty("密码")
    public String password;





}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

controller

@Api(tags = "HelloController控制类")
@RestController
public class HelloController {

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

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
    @GetMapping( value = "/user")
    public User user(){
        return new User();
    }

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



    @PostMapping( value = "/postt")
    public  User postt(@ApiParam("用户名") User user){
        return  user;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28