文档:https://springdoc.org
示例:https://github.com/springdoc/springdoc-openapi#demo-spring-boot-2-web-mvc-with-openapi-3
1. 依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.2</version>
</dependency>
2. 配置
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("springbootdemo-public")
.pathsToMatch("/public/**")
.build();
}
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("springbootdemo-admin")
.pathsToMatch("/admin/**")
.build();
}
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.info(info())
// .externalDocs(externalDocumentation())
.components(components())
.security(Lists.newArrayList(new SecurityRequirement().addList("Authorization")));
}
private ExternalDocumentation externalDocumentation() {
return new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs");
}
private Components components() {
return new Components()
.addSecuritySchemes("Authorization", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT"));
}
private Info info() {
return new Info()
.title("springbootdemoAPI")
.description("springbootdemoAPI相关文档")
.version("v1.0")
.contact(new Contact()
.name("开心")
.url("https://blog.ckx.ink")
.email("chenkaixin12121@163.com"))
.license(new License()
.name("Apache 2.0")
.url("https://opensource.org/licenses/Apache2.0"));
}
}
springdoc:
api-docs:
enabled: true
path: /api-docs
swagger-ui:
enabled: true
path: /doc.html
display-request-duration: true
groups-order: DESC
operationsSorter: method
disable-swagger-default-url: true
use-root-path: true
3. 测试
@Data
@Schema(description = "用户信息")
public class User {
@Schema(description = "用户名", required = true, minLength = 6, maxLength = 20)
private String username;
@Schema(description = "密码", required = true, minLength = 6, maxLength = 20)
private String password;
@Schema(description = "是否删除", hidden = true, allowableValues = {"0", "1"})
private Integer isDel;
}
@Tag(name = "admin", description = "管理接口")
@RestController
@RequestMapping("/admin")
public class AdminController {
@Operation(summary = "测试方法")
@GetMapping(value = "/sayHello")
public String sayHello(@Parameter(description = "名称", in = ParameterIn.QUERY) @RequestParam(required = false, defaultValue = "chenkaixin12121") String name) {
return "hello " + name;
}
@Operation(summary = "获取当前用户", security = {@SecurityRequirement(name = "Authorization")})
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "请求成功", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = User.class))}),
@ApiResponse(responseCode = "400", description = "客户端参数错误", content = @Content),
@ApiResponse(responseCode = "404", description = "请求路径不存在", content = @Content)
})
@GetMapping(value = "/getUser")
public User getUser() {
User user = new User();
user.setUsername("chenkaixin12121");
user.setPassword("123456");
return user;
}
}
@Tag(name = "public", description = "公共接口")
@RestController
@RequestMapping("/public")
public class PublicController {
@Operation(summary = "测试方法")
@GetMapping(value = "/sayHello")
public String sayHello(@Parameter(description = "名称", in = ParameterIn.QUERY) @RequestParam(required = false, defaultValue = "chenkaixin12121") String name) {
return "hello " + name;
}
}
访问:http://localhost:8080/doc.html