swagger参考网址:
官网:OpenAPI Design & Documentation Tools | Swaggerhttps://swagger.io/tools/
mvnrepository.swagger3:Maven Repository: io.swagger.core.v3 » swagger-annotations (mvnrepository.com)https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotationsmvnrepository.swagger2 和 swagger UI:Maven Repository: springfox (mvnrepository.com)https://mvnrepository.com/search?q=springfox
注解详细解释:
swagger简介
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。它是一个开源的框架,提供了完整的解决方案,用于构建、设计、文档和调用RESTful Web服务。Swagger可以让开发人员快速创建API文档,并支持自动生成客户端和服务端代码。它还提供了强大的功能,如API的发现、定义、测试和可视化等。
Swagger通过注解来自动生成API文档,使得开发人员可以专注于编写代码,而不需要手动编写大量的文档。此外,Swagger还支持多种语言和框架,如Java、Spring等,可以方便地集成到现有的项目中。
总之,Swagger是一个强大的工具,可以帮助开发人员快速构建和文档化RESTful风格的Web服务。
配置依赖
依赖引入
此处使用的 swagger3 所用的依赖是:
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.2.15</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
由于使用的springboot是3.2.0版本,导致无法使用 swagger2 依赖无法使用:
曾经(2.9.2版本也测试过了,用不了):
<dependency>
<groupId>io.springfox</groupId>-->
<artifactId>springfox-swagger2</artifactId>-->
<version>3.0.0</version>-->
</dependency>
Controller层配置
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
打开网址为:
Swagger UI (www.localhost)http://www.localhost:8080/swagger-ui/index.html
完成样式:
注解的变化
@Api(tags = "")
改为
@Tag(name = "")
@ApiModel(value="", description="")
改为
@Schema(name="", description="")
@ApiModelProperty(value = "", required = false)
改为
@Schema(name= "", description = "", required = false)
@ApiOperation(value = "", notes = "")
改为
@Operation(summary = "", description = "")
@ApiParam 改为 @Parameter
@ApiResponse(code = , message = "")
改为
@ApiResponse(responseCode = "", description = "")
原注解释意:
一些常常用的注解:
@Tag
描述:用于给 API 分组,用途类似于为 API 文档添加标签。
可用于:方法、类、接口。
属性:name:分组的名称。
@Operation
描述:用于描述 API 的操作。
可用于:方法。
属性:
summary:操作的摘要信息。
description:操作的详细描述。
tags:指定 @Tag 注解的对象数组,用于将操作归类到特定的分组。
parameters:指定 @Parameter 注解的对象数组,用于描述操作的输入参数。
responses:指定 @ApiResponse 注解的对象数组,用于描述操作的响应结果。
requestBody:指定 @RequestBody 注解的对象,用于描述操作的请求体。
@Parameter
描述:用于描述操作的输入参数。
可用于:方法。
属性:
name:参数的名称。
in:参数的位置,可以是 path、query、header、cookie 中的一种。
description:参数的描述。
required:参数是否必需,默认为 false。
schema:指定 @Schema 注解的对象,用于描述参数的数据类型。
@ApiResponse
描述:用于描述操作的响应结果。
可用于:方法。
属性:
responseCode:响应的状态码。
description:响应的描述。
content:指定 @Content 注解的对象数组,用于描述响应的内容。
这个swagger3而不是swagger2
首先swagger3展示的信息比swagger2要详细。
其次swagger3 配置比较方便只需要一个依赖,而swagger2需要有依赖
,以及config的配置文件同时需要@Configuation去注入,还需要@EnableSwagger2注解去启动,以及内容还需要写相关的@Bean才可以使用。
还有一点是这个项目完整的开发完了,这个帮助文档是要删除的不然会有一定的安全问题,swagger2这配置这么多,可能会在删除的时候有遗漏等。
最后就是swgagger2与springboot3有版本不兼容等问题,所以不推荐使用。
以下就是swagger2使用时需要的相关配置:
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
ServletContext servletContext = applicationContext.getBean(ServletContext.class);
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(Predicates.not(regex("/error.*")))
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("平台接口 v1.0")
.description("平台接口")
.contact(contact)
.version("1.0")
.build();
}
}
另外测试了一下那个spring scurity会不会拦截:
答案是:不登录会被拦截,登录了就可以进去,不需要重新输入用户名和密码。