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依赖

    org.springframework.boot
    spring-boot-starter-parent
    2.1.5.RELEASE
     




    UTF-8
    UTF-8
    1.8




    
    
        org.springframework.boot
        spring-boot-starter
    
    
    
    
        io.springfox
        springfox-swagger2
        2.5.0
    
    
    
    
        io.springfox
        springfox-swagger-ui
        2.5.0
    
    
    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
    
        org.springframework.boot
        spring-boot-starter-test
        test
    
    
    
    
        junit
        junit
    
    
    
    
        org.projectlombok
        lombok
        true
    

    
    
        com.alibaba
        fastjson
        1.2.46
    
    
    
    
        org.springframework.boot
        spring-boot-devtools
    

    
    
        org.quartz-scheduler
        quartz
        2.3.0
    

    
    
        org.apache.poi
        poi
        3.17
    

    
        org.apache.poi
        poi-ooxml
        RELEASE
    




    
        
        
            org.springframework.boot
            spring-boot-maven-plugin
        
    
    
    SpringBoot-one

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 users = Collections.synchronizedMap(new HashMap());
 5     @ApiOperation(value="获取用户列表", notes="")
 6     @RequestMapping(value={""}, method=RequestMethod.GET)
 7     public List getUserList() {
 8         List r = new ArrayList(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–举例说明

最后

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