springboot之spring-boot 2.3.x 整合swagger3.0.0
spring-boot 2.3.x 整合swagger3.0.0
| 环境 | 版本 |
|---|---|
| jdk | 1.8.0_201 |
| maven | 3.6.0 |
| Spring-boot | 2.3.3.RELEASE |
1、简介
Swagger UI 是一款 API 在线文档生成和调试工具。在需求不断变更的开发环境下，手动编写文档的效率实在太低；
在Swagger3版本中，减少了谷歌的guava依赖，更多的应用了java8的语法；新增了springboot流行的start启动包形式依赖；
主要配置属性如下：主要说一些常用的配置
@Api(tags = "测试接口")：用在请求的controller类上，表示对类的说明，tags=“说明该类的作用，可以在UI界面上看到的注解”
@ApiOperation("测试")：用在请求的方法上；value=方法的用途；notes=“方法的备注”
@ApiResponses：用在请求的方法上，表示一组响应;
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：请求的状态码，例如 200、401、403 ……
message：信息，例如"请求参数没填好"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明;
@ApiImplicitParam：用在方法上，表示一个请求参数描述；多在参与，用在@ApiImplicitParams中；
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {
//参数名
String name() default "";
//参数描述
String value() default "";
//参数默认值
String defaultValue() default "";
String allowableValues() default "";
//是否必传
boolean required() default false;
String access() default "";
//允许多个，当传入的参数为数组或者list时候，指定参数类型dataType()，属性设置为true；
boolean allowMultiple() default false;
//数据类型：这可以是类名或基础类型。
String dataType() default "";
//数据的class类
Class dataTypeClass() default Void.class;
/**
请求参数类型：
path：请求参数的获取：@PathVariable
query：请求参数的获取：@RequestParam
body：@RequestBody
header：请求参数的获取：@RequestHeader
form：表单数据
*/
String paramType() default "";
/** a single example for non-body type parameters*/
String example() default "";
//Examples for the parameter. Applies only to BodyParameters
Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
//Adds the ability to override the detected type
String type() default "";
//Adds the ability to provide a custom format
String format() default "";
//Adds the ability to set a format as empty
boolean allowEmptyValue() default false;
//adds ability to be designated as read only.
boolean readOnly() default false;
//adds ability to override collectionFormat with `array` types
String collectionFormat() default "";
}
@ApiModel:用于类上，表示一个返回响应数据的信息，或者传入的参数对象的内容：例如post请求；
@ApiModelProperty：用在属性上，描述响应类的属性
详细可以参看《github springfox》
2、构建一个基础的web项目
2.1、导入swagger的自动装配包
4.0.0
org.springframework.boot
spring-boot-starter-parent
2.3.3.RELEASE
com.badger
badger-spring-boot-securty
0.0.1-SNAPSHOT
badger-spring-boot-securty
UTF-8
1.8
3.1.1
org.springframework.boot
spring-boot-starter-web
io.springfox
springfox-boot-starter
3.0.0
org.springframework.boot
spring-boot-starter-test
test
org.junit.vintage
junit-vintage-engine
org.springframework.boot
spring-boot-maven-plugin
2.2、swagger的配置类
/**
* 基于Swagger生成API文档
* @EnableOpenApi：启动OpenApi的类； 之前是@EnableSwagger2
*/
@Configuration
@EnableOpenApi
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.badger.spring.boot.web")).paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("我是标题").description("我是描述").contact(new Contact("联系人", "www.baidu.com", "[email protected]"))
.version("1.0").build();
}
}
2.3、主启动类
@Api(tags = "测试接口")
@RestController
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) throws Exception {
SpringApplication.run(SwaggerApplication.class, args);
}
@ApiResponse(message = "测试", code = 200)
@ApiOperation("ceshi")
@GetMapping("/test")
public String test() {
return "test";
}
}
3、测试演示
直接启动springboot的启动类就可以了
访问地址 http://localhost:8080/swagger-ui/index.html#/