怎么在SpringBoot中利用Swagger2生成一个接口文档
本篇文章为大家展示了怎么在SpringBoot中利用Swagger2生成一个接口文档,内容简明扼要并且容易理解,绝对能使你眼前一亮,通过这篇文章的详细介绍希望你能有所收获。
成都创新互联长期为上1000家客户提供的网站建设服务,团队从业经验10年,关注不同地域、不同群体,并针对不同对象提供差异化的产品和服务;打造开放共赢平台,与合作伙伴共同营造健康的互联网生态环境。为峨眉山企业提供专业的网站建设、成都网站制作,峨眉山网站改版等技术服务。拥有10余年丰富建站经验和众多成功案例,为您定制开发。
准备工作
一个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
相关的包了。
org.springframework.boot spring-boot-starter-web io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
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
并提供了两个接口:
通过用户id获取用户
用户登录
@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
等,下面我们就来一一解释一下。
@Api,这个注解是用在Controller类上面的,可以对Controller做必要的说明。
@ApiOperation,作用在具体的方法上,其实就是对一个具体的API的描述。
@ApiParam,对API参数的描述。
到这里,其实我们的Swagger就已经可以有效果了,让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。
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生成一个接口文档
文章URL:http://scyanting.com/article/igdhgc.html