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>

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

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>

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

访问地址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("", "", "");

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());
}

@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());}*/@Beanpublic Docket docket(){return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());}//配置Swagger信息=apiInfoprivate 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());}
}

在这里插入图片描述

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();
}

配置是否启动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();
}

我只希望我的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();
}

application.properties

spring.profiles.active=dev

applicationdev.properties

server.port=8081

配置API文档分组

groupName("陈平安")

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

实体类配置

@Api(tags = “”)

类注释

@ApiModel(“”)

方法注释

@ApiOperatio

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

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