swagger2
更新到3后,再使用方法上发生了很大的变化,名称也变为OpenAPI3
。
官方文档
一、引入依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>${springdoc-openapi.version}</version>
</dependency>
server:
servlet:
context-path: /content
springdoc:
api-docs:
enabled: true
path: /v3/api-docs
swagger-ui:
enabled: true
path: /swagger-ui.html
openapi3
使用十分方便,做到这里后,你可以直接通过以下网址访问swagger
页面。
http://<ip>:<port>/content/swagger-ui/index.html
二、使用
1. @OpenAPIDefinition + @Info
用于定义整个 API
的信息,通常放在主应用类上。可以包括 API
的标题、描述、版本等信息。
@SpringBootApplication
@Slf4j
@OpenAPIDefinition(info = @Info(title = "内容管理系统", description = "对课程相关信息进行管理", version = "1.0.0"))
public class ContentApplication {
public static void main(String[] args) {
SpringApplication.run(ContentApplication.class, args);
}
}
2. @Tag
用于对 API
进行分组。可以在控制器类或方法级别上使用。
@Tag(name = "课程信息编辑接口")
@RestController("content")
public class CourseBaseInfoController {
}
3. @Operation
描述单个 API
操作(即一个请求映射方法)。可以提供操作的摘要、描述、标签等。
@Operation(summary = "课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(
PageParams params,
@RequestBody(required = false) QueryCourseParamsDto dto){
CourseBase courseBase = new CourseBase();
courseBase.setCreateDate(LocalDateTime.now());
return new PageResult<CourseBase>(new ArrayList<CourseBase>(List.of(courseBase)),20, 2, 10);
}
4. @Parameter
用于描述方法参数的额外信息,例如参数的描述、是否必需等。
@Operation(summary = "课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(
@Parameter(description = "分页参数") PageParams params,
@Parameter(description = "请求具体内容") @RequestBody(required = false) QueryCourseParamsDto dto){
CourseBase courseBase = new CourseBase();
courseBase.setCreateDate(LocalDateTime.now());
return new PageResult<CourseBase>(new ArrayList<CourseBase>(List.of(courseBase)),20, 2, 10);
}
5. @Schema
描述模型的结构。可以用于类级别(标注在模型类上)或字段级别。
@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageParams {
//当前页码
@Schema(description = "页码")
private Long pageNo = 1L;
//每页记录数默认值
@Schema(description = "每页条目数量")
private Long pageSize =10L;
}
6. @ApiResponse
描述 API
响应的预期结果。可以指定状态码、描述以及返回类型。文章来源:https://www.toymoban.com/news/detail-814082.html
@ApiResponse(responseCode = "200", description = "Successfully retrieved user")
public User getUserById(@PathVariable Long id) {
}
文章来源地址https://www.toymoban.com/news/detail-814082.html
到了这里,关于SpringBoot3整合OpenAPI3(Swagger3)的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!