Swagger介绍及基本使用

最新推荐文章于 2024-04-30 20:07:12 发布

嗯兮

最新推荐文章于 2024-04-30 20:07:12 发布

阅读量3.8k

点赞数

文章标签： spring spring boot java

本文链接：https://blog.csdn.net/qq_51106567/article/details/131562549

版权

6. Swagger

6.1 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox即可使用Swagger。

主要作用：

使得前后端分离开发更加方便，有利于团队协作
接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
功能测试

主要依赖介绍：

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成
Swagger-js: 用于JavaScript的Swagger实现。Swagger-node-express: Swagger模块，用于node.js的Express web应用框架
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

6.2 基本使用

下面是一个简单的在Spring Boot中使用Swagger的案例：如果报错了可以看一下异常那一小节

添加Swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

创建Swagger配置类

创建一个名为SwaggerConfig的Java类，并添加以下内容：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket coreApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(adminApiInfo())
                .groupName("adminApi")
                .select()
                .paths(PathSelectors.any())//路径下的接口会暴露给Swagger监控
                .build();
    }
    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                .title("api文档")
                .description("接口描述")
                .version("1.0")
                .contact(new Contact("","",""))
                .build();
    }
}

这个类使用了@Configuration注解，表示这是一个配置类。@EnableSwagger2注解开启了Swagger的支持。Docket是Swagger的主要配置类，它定义了API的详细信息，包括标题、描述和版本等信息。

添加Swagger注解

在控制器类或控制器方法上添加Swagger注解，例如：

@RestController
@RequestMapping("/api")
@Api(value = "API", tags = { "API" })
public class ApiController {

    @GetMapping("/user")
    @ApiOperation(value = "save user", notes = "save a user")
    public String save() {
        return "save a user success!";
    }
}

@Api注解表示这是一个API类，value属性表示API的名称，tags属性表示API的标签。

@ApiOperation注解表示这是一个API操作，value属性表示操作的名称，notes属性表示操作的描述。

运行应用程序并访问Swagger UI

启动应用程序并在浏览器中访问以下URL：

http://localhost:8080/swagger-ui.html

这将打开Swagger UI，您可以在其中查看你的API文档并测试API。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-9462mYHA-1688556459158)(C:\Users\昭晞\Desktop\QQ截图20230705192545.png)]

6.3 Swagger常见注解

以下是Swagger常见注解的参数说明及例子：

@Api

@Api是用于描述整个API的信息，包括API的名称、描述、作者等信息。它可以用在类上。

参数说明：

value：API的名称。
tags：API的标签，用于对API进行分类。

示例：

@RestController
@RequestMapping("/api")
@Api(value = "API", tags = { "API" })
public class ApiController {

    // ...
}

@ApiOperation

@ApiOperation是用于描述API的操作，包括操作名称、描述、参数信息等。它可以用在方法上。

参数说明：

value：操作名称。
notes：操作描述。
response：响应类型。

示例：

@GetMapping("/hello")
@ApiOperation(value = "save user", notes = "save a user")
public String save() {
    return "save a user success";
}

@ApiParam

@ApiParam是用于描述API的参数信息，包括参数名称、描述、是否必填等信息。它可以用在方法的参数上。

参数说明：

value：参数名称。
required：是否必填。
defaultValue：参数的默认值。
allowableValues：参数的可选值。
example：参数的示例值。

示例：

@PostMapping("/user")
@ApiOperation(value = "Create user", notes = "Create a new user")
public ResponseEntity<User> createUser(
        @ApiParam(value = "User object", required = true) @RequestBody User user) {

    // ...
}

@ApiModel

@ApiModel是用于描述数据模型，包括模型名称、描述、属性等信息。它可以用在类上。

参数说明：

value：模型名称。
description：模型描述。

示例：

@ApiModel(description = "User object")
public class User {

    @ApiModelProperty(value = "User ID", required = true)
    private Long id;

    @ApiModelProperty(value = "User name", required = true)
    private String name;

    // ...
}

@ApiModelProperty

@ApiModelProperty是用于描述数据模型的属性，包括属性名称、描述、是否必填等信息。它可以用在类的属性上。

参数说明：

value：属性名称。
required：是否必填。
defaultValue：属性的默认值。
allowableValues：属性的可选值。
example：属性的示例值。

示例：

@ApiModel(description = "User object")
public class User {

    @ApiModelProperty(value = "User ID", required = true)
    private Long id;

    @ApiModelProperty(value = "User name", required = true)
    private String name;

    // ...
}

@ApiResponse

@ApiResponse是用于描述API的返回结果，包括返回码、返回信息等信息。它可以用在方法上。

参数说明：

code：返回码。
message：返回信息。
response：响应类型。

示例：

@GetMapping("/user/{id}")
@ApiOperation(value = "Get user by ID", notes = "Get user by ID")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = User.class),
        @ApiResponse(code = 404, message = "Not found")
})
public ResponseEntity<User> getUserById(
        @ApiParam(value = "User ID", required = true) @PathVariable Long id) {

    // ...
}

@ApiResponses

@ApiResponses是用于描述API的多个返回结果，可以包含多个@ApiResponse注解。它可以用在方法上。

参数说明：

value：返回结果数组。

示例：

@PostMapping("/user")
@ApiOperation(value = "Create user", notes = "Create a new user")
@ApiResponses(value = {
        @ApiResponse(code = 201, message = "Created", response = User.class),
        @ApiResponse(code = 400, message = "Bad request")
})
public ResponseEntity<User> createUser(
        @ApiParam(value = "User object", required = true) @RequestBody User user) {

    // ...
}

@ApiIgnore

@ApiIgnore是用于忽略某个API，可以用在类或方法上。

示例：

@ApiIgnore
@GetMapping("/secret")
public String secret() {
    return "Secret API";
}

@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParams：参数说明

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

6.4 Swagger配置

Swagger常见的配置如下：

@Configuration
@EnableSwagger2//开启Swagger
@ComponentScan(basePackages = { "com.example.demo" })//配置扫描包路径
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//导入api基本说明信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))//基础包路径
                .paths(PathSelectors.any("/api/**"))//
                .build();
    }
//配置Swagger API信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo API")//api主题（类似于大标题）
                .description("This is a demo API")//描述说明
                .version("1.0.0")//版本
                .build();//构建ApiInfo对象
    }
    //配置Swagger安全认证
    private ApiKey apiKey() {
        return new ApiKey("JWT", "Authorization", "header");//认证方式JWT令牌，
    }
//security安全
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
    }
//authorization批准
    private List<SecurityReference> defaultAuth() {//范围
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
    }
}

6.5 异常

大致信息：

org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’;

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.14.jar:5.3.14]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_372]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.14.jar:5.3.14]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.6.2.jar:2.6.2]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:730) [spring-boot-2.6.2.jar:2.6.2]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:412) [spring-boot-2.6.2.jar:2.6.2]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:302) [spring-boot-2.6.2.jar:2.6.2]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1301) [spring-boot-2.6.2.jar:2.6.2]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1290) [spring-boot-2.6.2.jar:2.6.2]
	at com.zhaoxi.swaggertest.SwaggerTestApplication.main(SwaggerTestApplication.java:10) [classes/:na]
Caused by: java.lang.NullPointerException: null
	at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:112) ~[springfox-spi-2.9.2.jar:null]
	at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:109) ~[springfox-spi-2.9.2.jar:null]
	at com.google.common.collect.ComparatorOrdering.compare(ComparatorOrdering.java:37) ~[guava-20.0.jar:na]
	at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_372]
	at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_372]
	at java.util.Arrays.sort(Arrays.java:1438) ~[na:1.8.0_372]
	at com.google.common.collect.Ordering.sortedCopy(Ordering.java:855) ~[guava-20.0.jar:na]
	at springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider.requestHandlers(WebMvcRequestHandlerProvider.java:57) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:138) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:135) ~[springfox-spring-web-2.9.2.jar:null]
	at com.google.common.collect.Iterators$7.transform(Iterators.java:750) ~[guava-20.0.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
	at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:52) ~[guava-20.0.jar:na]
	at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:50) ~[guava-20.0.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:249) ~[guava-20.0.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:209) ~[guava-20.0.jar:na]
	at com.google.common.collect.FluentIterable.toList(FluentIterable.java:614) ~[guava-20.0.jar:na]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.defaultContextBuilder(DocumentationPluginsBootstrapper.java:111) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.buildContext(DocumentationPluginsBootstrapper.java:96) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:167) ~[springfox-spring-web-2.9.2.jar:null]
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:178) ~[spring-context-5.3.14.jar:5.3.14]
	... 14 common frames omitted

报错原因： SpringBoot 与 Swagger2 版本冲突原因。具体的版本冲突范围未测量，我的SpringBoot2.6.2即以上版本都会与Swagger2.9.2及以上版本冲突。
解决方案：

方案一：将SpringBoot版本降低到2.6以下。我的2.6.2以下就是2.4.5，没报错。
方案二：在application.yml文件中添加以下配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher #解决Spring Boot与Swagger2版本冲突问题

嗯兮

关注

0
点赞
踩
22

收藏

觉得还不错? 一键收藏
打赏
1
评论
Swagger介绍及基本使用

Swagger基本使用，SpringBoot整合Swagger，版本冲突解决
复制链接

扫一扫

Swagger介绍及基本使用

6. Swagger

6.1 简介

6.2 基本使用

6.3 Swagger常见注解

6.4 Swagger配置

6.5 异常

“相关推荐”对你有帮助么？