java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > SpringBoot集成Swagger2

SpringBoot中集成Swagger2及简单实用

作者:秋天code

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等,这篇文章主要介绍了SpringBoot中集成Swagger2,需要的朋友可以参考下

介绍

Swagger是非常流行的API框架,能够自动生成RESTFul 风格的API文档,还可以在线测试后台接口。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等。
前后端分离的开发模式下,前端通过后端的API文档来进行开发和联调,效率更高。
Swagger就是帮助后端生成API文档的工具

简单使用

在SpringBoot中集成Swagger2,(等会说一个更简单的用法)。

引入依赖

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

配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 将负责生成摘要的Bean提供出去
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 用来设置文档元信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //版本号
                .version("1.0.0")
                .build();
    }
}

使用
因为Swagger帮助我们生成RestFul风格的文档,所以被修饰的接口方法必须是类似于@GetMapping@PostMapping@DeleteMapping,不能是一个笼统的@RequestMapping
下面会有详细的常用注解说明,此处只是想要来快速看一下效果

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "退出登录")
    public String logout(String username){
        return "退出登录成功";
    }
}

接下来访问http://ip:port/swagger-ui.html,会看到

SpringBoot版本与Swagger版本的冲突问题

如果你访问Swagger的文档地址后,发现是404,无法访问,那么大概是SpringBoot的版本问题

注意:
如果你的SpringBoot是2.6.x及更高,那么与Swagger2是不兼容的,因为SpringMVC的处理映射匹配的方式发生了变化。
需要在SpringBoot的配置文件中通过添加配置来使springboot2.6.x以后的版本来适配Swagger2
不要试图通过@EnableWebMvc来解决,同样会导致404

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

常用注解

Swagger的核心就是我们常用的这几个注解

@Api

一般用来标注在Controller上,注意此Controller要是一个RestController。

注解说明
@Api一般用在Controller类上,Swagger会扫描被此注解标注的类,并生成一个文档分类
@ApiOperation用在接口方法上,对该接口方法进行描述
@ApiModel用在实体类上,为此实体类生成说明文档
@ApiParam用来接口参数上,用来对此请求参数做说明
@ApiModelProperty用来实体类中的属性上,对此属性做说明
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
}

属性:

@ApiOperation

次注解用在方法上,对该接口进行描述。

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

属性:

@ApiParam

用在接口的参数上,用来对该参数进行修饰
属性:

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(@ApiParam(name="username", required = true) String username, @ApiParam(name="password",required = true) String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

@ApiResponse

用在方法上,对接口的返回内容进行描述
常用属性:

    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponse(code = 200,message = "查询成功",response = User.class)
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiResponses

如果返回的结果有多种,则可以使用@ApiResponses注解,此注解只有一个属性value,是一个@ApiResponse的数组。
其中包含多个@ApiResponse,每个@ApiResponse都是一种响应结果

    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = User.class),
            @ApiResponse(code = 403, message = "你还没有权限")
    }
    )
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiModel

属性:

value,标识名,如果不填,则会以类名作为valuedescription,类的描述信息
实体类上标注了此类后,会将所有的属性进行描述

@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
    private String username;
    private String password;
    private String sex;
    private Integer age;
}

一般都是直接@ApiModel注解,不用属性

@ApiProperty

如果需要对实体类中的属性进行单独的设置,那么就需要使用@ApiProperty属性了
常用属性:

@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
    @ApiModelProperty(value = "用户名",required = true)
    private String username;
    @ApiModelProperty(hidden = true)
    private String password;
    private String sex;
    private Integer age;
}

参考文档:
SpringBoot与Swagger2版本不兼容的问题!!
Failed to start bean ‘documentationPluginsBootstrapper‘; nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
Springboot ✚ Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
swagger-ui.html页面无法打开解决方案_Alphathur的博客-CSDN博客

到此这篇关于SpringBoot中集成Swagger2的文章就介绍到这了,更多相关SpringBoot集成Swagger2内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

您可能感兴趣的文章:
阅读全文