怎么在SpringBoot中利用Swagger2生成一个接口文档

发布时间:2021-04-14 18:06:43 作者:Leah
来源:亿速云 阅读:269

本篇文章为大家展示了怎么在SpringBoot中利用Swagger2生成一个接口文档,内容简明扼要并且容易理解,绝对能使你眼前一亮,通过这篇文章的详细介绍希望你能有所收获。

准备工作

一个SpringBoot项目,可以直接去官网 生成一个demo 。

一个用户类。

package cn.itweknow.springbootswagger.model;

import java.io.Serializable;


public class User implements Serializable {

 private Integer id;

 private String name;

 private String password;

 private String email;
}

项目依赖

Web Service肯定是一个Web项目,所以我们这里依赖了 spring-boot-starter-web 包,其他两个包就是和 Swagger 相关的包了。

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<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配置

Springfox Docket实例为Swagger配置提供了便捷的配置方法以及合理的默认配置。我们将通过创建一个Docket实例来对Swagger进行配置,具体配置如下所示。

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

 @Bean
 public Docket productApi() {
  return new Docket(DocumentationType.SWAGGER_2).select()
    // 扫描的包路径
    .apis(RequestHandlerSelectors.basePackage("cn.itweknow.springbootswagger.controller"))
    // 定义要生成文档的Api的url路径规则
    .paths(PathSelectors.any())
    .build()
    // 设置swagger-ui.html页面上的一些元素信息。
    .apiInfo(metaData());
 }

 private ApiInfo metaData() {
  return new ApiInfoBuilder()
    // 标题
    .title("SpringBoot集成Swagger2")
    // 描述
    .description("这是一篇博客演示")
    // 文档版本
    .version("1.0.0")
    .license("Apache License Version 2.0")
    .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
    .build();
 }

 @Override
 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
  registry.addResourceHandler("swagger-ui.html")
    .addResourceLocations("classpath:/META-INF/resources/");

  registry.addResourceHandler("/webjars/**")
    .addResourceLocations("classpath:/META-INF/resources/webjars/");
 }
}

上述代码中的addResourceHandlers方法添加了两个资源处理程序,这段代码的主要作用是对Swagger UI的支持。

API文档

好了,到这一步,我们已经在一个SpringBoot项目中配置好了Swagger。现在,我们就来看一下如何去使用他。首先我们定义了一个 Controller 并提供了两个接口:

@RestController
@RequestMapping("/user")
@Api(description = "用户相关接口")
public class UserController {

 /**
  * 通过id查询用户
  * @return
  */
 @RequestMapping(value = "/get", method = RequestMethod.GET)
 @ApiOperation("根据id获取用户")
 public User getUserById(@ApiParam(value = "用户id") Integer id) {
  return new User();
 }

 @RequestMapping(value = "/login", method = RequestMethod.POST)
 @ApiOperation("用户登录")
 public User login(@RequestBody User user) {
  return new User();
 }
}

相信大家都注意到了,这个 Controller 里面多了很多新的注解,比如说 @Api , @ApiOperation 等,下面我们就来一一解释一下。

到这里,其实我们的Swagger就已经可以有效果了,让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。

怎么在SpringBoot中利用Swagger2生成一个接口文档

Model

在上面的图中可以看到在页面的下方有一个Models的标签,那么这个是啥呢。其实这个就是我们API中出现的一些对象的文档,我们也可以通过注解来对这些对象中的字段做一些说明,以方便使用者理解。以文章开头提到的 User 类来做一个说明。

@ApiModel("用户实体")
public class User implements Serializable {

 @ApiModelProperty(value = "用户id")
 private Integer id;

 @ApiModelProperty(value = "用户名称", required = true)
 private String name;

 @ApiModelProperty(value = "密码", required = true)
 private String password;

 @ApiModelProperty(value = "用户邮箱")
 private String email;
}

我们来看一下 User 类在Swagger上是如何展示的:

怎么在SpringBoot中利用Swagger2生成一个接口文档

上述内容就是怎么在SpringBoot中利用Swagger2生成一个接口文档,你们学到知识或技能了吗?如果还想学到更多技能或者丰富自己的知识储备,欢迎关注亿速云行业资讯频道。

推荐阅读:
  1. Spring boot集成swagger2如何生成接口文档
  2. SpringBoot结合swagger2如何生成接口文档

免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。

springboot swagger2

上一篇:怎么在angularjs中使用http与后台进行交互

下一篇:怎么在C++中使用内部类

相关阅读

您好,登录后才能下订单哦!

密码登录
登录注册
其他方式登录
点击 登录注册 即表示同意《亿速云用户服务条款》