专栏首页大道七哥Springboot集成swagger2生成接口文档

Springboot集成swagger2生成接口文档

【转载请注明】:

原文出处https://www.cnblogs.com/jstarseven/p/11509884.html 作者:jstarseven 码字挺辛苦的.....


一、Swagger介绍

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件。

二、使用swagger优势

1、对于后端开发人员来说

  • 不用再手写Wiki接口拼大量参数,避免手写错误
  • 对代码侵入性低,采用全注解的方式,开发简单
  • 方法参数名修改、新增、减少参数都可以直接生效,不用手动维护
  • 缺点:增加了开发成本,写接口还得再写一套参数配置

2、对前端开发来说

  • 后端只需要定义好接口,会自动生成文档,接口功能、参数一目了然
  • 联调方便,如果出了问题,直接测试接口,实时检查参数和返回值,就可以快速定位是前端还是后端的问题

3、对于测试来说

  • 但对于测试没有前端界面UI的功能,可以直接用它来测试接口
  • 操作简单,不用了解具体代码就可以操作

三、springboot集成swagger使用

1、新建maven项目(结构如下:)

2、配置pom.xml文件

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 4     <modelVersion>4.0.0</modelVersion>
 5     <parent>
 6         <groupId>org.springframework.boot</groupId>
 7         <artifactId>spring-boot-starter-parent</artifactId>
 8         <version>2.1.3.RELEASE</version>
 9         <relativePath/>
10     </parent>
11     <groupId>com.dds.sbswagger</groupId>
12     <artifactId>sb-swagger</artifactId>
13     <version>0.0.1-SNAPSHOT</version>
14     <name>sb-swagger</name>
15     <description>Demo project for Spring Boot</description>
16 
17     <properties>
18         <java.version>1.8</java.version>
19     </properties>
20     <dependencies>
21         <dependency>
22             <groupId>org.springframework.boot</groupId>
23             <artifactId>spring-boot-starter-web</artifactId>
24         </dependency>
25         <dependency>
26             <groupId>org.springframework.boot</groupId>
27             <artifactId>spring-boot-starter-test</artifactId>
28             <scope>test</scope>
29         </dependency>
30         <dependency>
31             <groupId>io.springfox</groupId>
32             <artifactId>springfox-swagger2</artifactId>
33             <version>2.9.2</version>
34         </dependency>
35         <dependency>
36             <groupId>io.springfox</groupId>
37             <artifactId>springfox-swagger-ui</artifactId>
38             <version>2.9.2</version>
39         </dependency>
40         <dependency>
41             <groupId>org.projectlombok</groupId>
42             <artifactId>lombok</artifactId>
43             <version>1.18.6</version>
44         </dependency>
45     </dependencies>
46     <build>
47         <plugins>
48             <plugin>
49                 <groupId>org.springframework.boot</groupId>
50                 <artifactId>spring-boot-maven-plugin</artifactId>
51             </plugin>
52         </plugins>
53     </build>
54 </project>

3、程序启动类

 1 package com.dds.sbswagger;
 2 
 3 import lombok.extern.slf4j.Slf4j;
 4 import org.springframework.boot.SpringApplication;
 5 import org.springframework.boot.autoconfigure.SpringBootApplication;
 6 
 7 /**
 8  * @author dds
 9  */
10 @SpringBootApplication
11 @Slf4j
12 public class SbSwaggerApplication {
13 
14     public static void main(String[] args) {
15         SpringApplication.run(SbSwaggerApplication.class, args);
16         log.info("\n----------------------------------------------------------\n\t" +
17                 "Application demo is running! Access URLs:\n\t" +
18                 "swagger-ui: \thttp://127.0.0.1:8080/swagger-ui.html\n\t" +
19                 "----------------------------------------------------------");
20     }
21 
22 }

4、SwaggerConfig配置类

 1 package com.dds.sbswagger.config;
 2 
 3 import io.swagger.annotations.ApiOperation;
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.PathSelectors;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.service.ApiInfo;
 9 import springfox.documentation.service.Contact;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spring.web.plugins.Docket;
12 import springfox.documentation.swagger2.annotations.EnableSwagger2;
13 
14 import java.util.Collections;
15 
16 /**
17  * @author DDS
18  * @date 2019/9/10 13:55
19  */
20 @Configuration
21 @EnableSwagger2
22 public class SwaggerConfig {
23     @Bean
24     public Docket api() {
25         return new Docket(DocumentationType.SWAGGER_2)
26                 .select()
27                 .apis(RequestHandlerSelectors.basePackage("com.dds.sbswagger.controller"))
28                 //加了ApiOperation注解的类,才生成接口文档
29                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
30                 .paths(PathSelectors.any())
31                 .build()
32                 .apiInfo(apiInfo());
33     }
34 
35     private ApiInfo apiInfo() {
36         return new ApiInfo(
37                 "Spring Boot项目集成Swagger实例文档",
38                 "我的微信公众号:大道七哥,欢迎大家关注。",
39                 "API V1.0",
40                 "Terms of service",
41                 new Contact("大道七哥", "https://www.cnblogs.com/jstarseven/", "jstarseven@163.com"),
42                 "Apache", "http://www.apache.org/", Collections.emptyList());
43     }
44 }

5、实体类model

 1 package com.dds.sbswagger.model;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 import lombok.Data;
 6 
 7 /**
 8  * @author DDS
 9  * @date 2019/9/10 13:55
10  */
11 @ApiModel("用户实体")
12 @Data
13 public class User {
14 
15     /**
16      * 用户Id
17      */
18     @ApiModelProperty("用户id")
19     private int id;
20 
21     /**
22      * 用户名
23      */
24     @ApiModelProperty(value = "用户姓名", example = "zhangdan", required = true)
25     private String name;
26 
27     /**
28      * 用户地址
29      */
30     @ApiModelProperty(value = "用户地址", example = "北京市海淀区", required = true)
31     private String address;
32 
33     /**
34      * 用户手机号
35      */
36     @ApiModelProperty(value = "用户手机号", example = "15689652367", required = true)
37     private String phone;
38 
39     /**
40      * 用户年龄
41      */
42     @ApiModelProperty(value = "用户年龄", example = "24", required = true)
43     private Integer age;
44 
45 }

6、接口开发

 1 package com.dds.sbswagger.controller;
 2 
 3 import com.dds.sbswagger.model.User;
 4 import io.swagger.annotations.*;
 5 import org.springframework.web.bind.annotation.*;
 6 
 7 /**
 8  * @author DDS
 9  * @date 2019/9/10 13:55
10  */
11 @RestController
12 @RequestMapping("/user")
13 @Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
14 public class UserController {
15 
16     @PostMapping("/add")
17     @ApiOperation(value = "新增用户接口", notes = "手机号、密码都是必输项,年龄随边填,但必须是数字")
18     @ApiImplicitParams({
19             @ApiImplicitParam(name = "name", value = "用户名称", required = true, paramType = "form"),
20             @ApiImplicitParam(name = "address", value = "用户地址", required = true, paramType = "form"),
21             @ApiImplicitParam(name = "phone", value = "用户手机号", required = true, paramType = "form"),
22             @ApiImplicitParam(name = "age", value = "用户年龄", required = true, paramType = "form", dataType = "Integer")
23     })
24     public boolean addUser(@RequestBody User user) {
25         return false;
26     }
27 
28     @ApiOperation("通过id查找用户接口")
29     @GetMapping("/find/{id}")
30     public User findById(@PathVariable("id") int id) {
31         return new User();
32     }
33 
34     @ApiOperation("更新用户信息接口")
35     @PutMapping("/update")
36     @ApiResponses({
37             @ApiResponse(code = 400, message = "请求参数没填好"),
38             @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
39             @ApiResponse(code = 405, message = "未知错误")
40     })
41     public boolean update(@RequestBody User user) {
42         return true;
43     }
44 
45     @ApiOperation("删除用户接口")
46     @DeleteMapping("/delete/{id}")
47     public boolean delete(@PathVariable("id") int id) {
48         return true;
49     }
50 }

7、swagger界面显示


-END-

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 如何给女朋友解释为什么12306会用户信息泄露

    挂断电话后,我赶紧登录12306改掉了我的密码,还好我各个网站的密码不一样,这样就能很好的避免被撞库了。

    帅地
  • (2)交换排序之冒泡排序

    title: (2)交换排序之冒泡排序 date: 2019-02-10 13:00:00 +0800 update: 2019-02-10 13:00:...

    suveng
  • TIOBE 9 月排行榜:Java没有悬念,PHP 正努力保住前十位置

    自 2001 年 TIOBE 指数开始以来, PHP 始终保持在榜单的前 10 位。它甚至是 2004 年 TIOBE 的年度编程语言。直到 2009 年底,一...

    奋斗蒙
  • 锁汇总

    个人博客:https://suveng.github.io/blog/​​​​​​​

    suveng
  • Cloud Studio 2.0 正式上线

    今日,CODING 创始人兼 CEO 张海龙受邀出席由极客邦科技和 InfoQ 中国 主办的顶级技术盛会 GMTC ,并在大会开幕时做了主题分享,向大家隆重推出...

    CODING研发管理系统
  • java之@Controller和@RestController以及@GetMapping和@PostMapping接收参数的格式使用

    一、1.使用@Controller 注解,在对应的方法上,视图解析器可以解析return 的jsp,html页面,并且跳转到相应页面

    botkenni
  • 一个MySQL时间戳精度引发的血案

    最近工作中遇到两例mysql时间戳相关的问题,一个是mysql-connector-java和msyql的精度不一致导致数据查不到;另一例是应用服务器时区错误导...

    猿天地
  • 干货分享 | GraphQL 数据聚合层

    先回到会议的主题,为什么会开这么一个会议?原本这个会议报名的时候希望可以控制到 100 人之内,不要超过 120 人,结果报到 250 人还爆满了,后来没有办法...

    CODING研发管理系统
  • 一起来看,社区大佬揭开 Creator 2.1.2 材质系统的神秘面纱!

    最近空闲的时候,研究了一下 2.1.2 版本的 shader,这里单独提出来一个说明一下,希望对想了解 2.1.2 的童鞋有所帮助。

    张晓衡
  • 跟我一起深入浅出学编译

    众所周知,编译技术是计算机科学史上的明珠之一。如果说整个互联网的发展是构建在编译技术和编程语言之上也毫不为过。

    iMike

扫码关注云+社区

领取腾讯云代金券