Springboot系列——集成swagger2，生成API

Springboot系列——集成swagger2，生成API

Swagger简介

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

很多时候由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
为了解决这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。

Springboot中swagger2快速集成

1.配置pom依赖

<!--父依赖-->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.5.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<!--编码格式-->
<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
</properties>

<dependencies>

    <!--核心依赖-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    
    <!--Swagger2-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.5.0</version>
    </dependency>
    
    <!--Swagger-ui-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
    
    <!-- 引入web依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- 引入test测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    
    <!-- Junit 单元测试 依赖 -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
    </dependency>
    
    <!-- 引入Lombock依赖 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!--阿里fastjson-->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.46</version>
    </dependency>
    
    <!-- Spring Boot devtools 热部署 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
    </dependency>

    <!--quartz定时任务-->
    <dependency>
        <groupId>org.quartz-scheduler</groupId>
        <artifactId>quartz</artifactId>
        <version>2.3.0</version>
    </dependency>

    <!--Excel导入导出-->
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi</artifactId>
        <version>3.17</version>
    </dependency>

    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
        <version>RELEASE</version>
    </dependency>

</dependencies>

<build>
    <plugins>
        <!-- SpringBoot 项目打jar包的Maven插件 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
    <!-- SpringBoot项目打包jar名称 -->
    <finalName>SpringBoot-one</finalName>
</build>

2.添加配置文件

/**

• @author 倾宸
• @date 2019/6/24 13:47
• 通过 @Configuration 注解，让Spring来加载该类配置。
• 再通过 @EnableSwagger2 注解来启⽤Swagger2
  /
  @Configuration
  @EnableSwagger2
  public class SpringSwaggerConfig {
  /*
  • @Author LiuSenChuan
  • @Description //TODO
  • @Date 2019/6/24
  • 通过createRestApi函数创建Docket的bean之后，
  • apiInfo用来创建该API的信息，
  • select函数返回一个ApiSelectorBuilder实例用来控制那些接口暴露给swagger来展现。
    **/
    @Bean
    public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage(“com.jmccms”))
    .paths(PathSelectors.any())
    .build();
    }
    private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
    .title(“Swagger2构建RESTful APIs”)
    .description(“果果”)
    .termsOfServiceUrl(“https://blog.csdn.net/qq_44741038”)
    .version(“1.0”)
    .build();
    }
    }

3.编写启动类

/**

• @author 倾宸
• @date 2019/6/19 9:24
  */

@EnableSwagger2
@SpringBootApplication
public class SpringBootOApplication{

/**
 * @Author LiuSenChuan
 * @Description 启动类
 * @Date  2019/6/19
 * @Param
 * @return
 **/
public static void main(String[] args) {
    SpringApplication.run(SpringBootOApplication.class, args);
}

}

4.注：

启动类中添加 @EnableSwagger2注解，开启swagger；

对接口进行api文档注解，不进行注解也会由相关的api，但是没有接口的详细描述，只有开发人员可以看懂。

5.注解例如：

 1 @RestController
 2 @RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
 3 public class UserController {
 4     static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
 5     @ApiOperation(value="获取用户列表", notes="")
 6     @RequestMapping(value={""}, method=RequestMethod.GET)
 7     public List<User> getUserList() {
 8         List<User> r = new ArrayList<User>(users.values());
 9         return r;
10     }
11     @ApiOperation(value="创建用户", notes="根据User对象创建用户")
12     @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
13     @RequestMapping(value="", method=RequestMethod.POST)
14     public String postUser(@RequestBody User user) {
15         users.put(user.getId(), user);
16         return "success";
17     }
18     @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
19     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
20     @RequestMapping(value="/{id}", method=RequestMethod.GET)
21     public User getUser(@PathVariable Long id) {
22         return users.get(id);
23     }
24     @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
25     @ApiImplicitParams({
26             @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
27             @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
28     })
29     @RequestMapping(value="/{id}", method=RequestMethod.PUT)
30     public String putUser(@PathVariable Long id, @RequestBody User user) {
31         User u = users.get(id);
32         u.setName(user.getName());
33         u.setAge(user.getAge());
34         users.put(id, u);
35         return "success";
36     }
37     @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
38     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
39     @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
40     public String deleteUser(@PathVariable Long id) {
41         users.remove(id);
42         return "success";
43     }
44 }

Swagger常用注解

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：
@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

@ApiOperation() 用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法
表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

最后

更多参考精彩博文请看这里：倾宸的博客
喜欢博主的小伙伴可以加个关注、点个赞哦，持续更新嘿嘿！***