1. SpringBoot整合Swagger2

强大的api文档工具，让开发人员摆脱繁杂的文档苦海。

1.1 导入依赖

1
2
3
4
5
<dependency>
         <groupId>com.spring4all</groupId>
         <artifactId>swagger-spring-boot-starter</artifactId>
         <version>1.9.1.RELEASE</version>
     </dependency>

1.2 启动类添加@EnableSwagger2Doc注解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package com.mszlu.union;

import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@EnableSwagger2Doc
@SpringBootApplication
public class App {

    public static void main(String[] args) {
        SpringApplication.run(App.class,args);
    }
}

1.3 配置

1
2
3
4
5
6
7
8
9
10
11
swagger.title=码神之路-swagger2
swagger.description=码神之路-swagger2 描述信息
swagger.version=2.9.2
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=码神之路
swagger.contact.url=http://blog.mszlu.com
swagger.contact.email=码神之路
swagger.base-package=com.mszlu
swagger.base-path=/**

各参数配置含义如下：

  • swagger.title：标题
  • swagger.description：描述
  • swagger.version：版本
  • swagger.license：许可证
  • swagger.licenseUrl：许可证URL
  • swagger.termsOfServiceUrl：服务条款URL
  • swagger.contact.name：维护人
  • swagger.contact.url：维护人URL
  • swagger.contact.email：维护人email
  • swagger.base-package：swagger扫描的基础包，默认：全扫描
  • swagger.base-path：需要处理的基础URL规则，默认：/**

1.4 添加文档内容

在整合完Swagger之后，在http://localhost:8081/swagger-ui.html页面中可以看到，关于各个接口的描述还都是英文或遵循代码定义的名称产生的。

这些内容对用户并不友好，所以我们需要自己增加一些说明来丰富文档内容。

如下所示，我们通过@Api，@ApiOperation注解来给API增加说明、通过@ApiImplicitParam、@ApiModel、@ApiModelProperty注解来给参数增加说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package com.mszlu.union.pojo;

import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
//User 对象 如何和 user表关联起来

@Data
//@TableName("user")
// tb_user
//@TableName("tb_user") mybatis-plus.global-config.db-config.table-prefix=tb_
@ApiModel(description="用户实体")
public class User {
    @ApiModelProperty("用户编号")
    private Long id;
    @ApiModelProperty("用户姓名")
    //@TableField("name")// 表的字段
    private String name;
    //表字段 是user_name
//    @TableField("user_name") 可以不加 _会替换为驼峰写法
//    private String userName;
    private String email;
    @ApiModelProperty("用户年龄")
    private Integer age;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
package com.mszlu.union.controller;

import com.mszlu.dubbo.service.DubboUserService;
import com.mszlu.union.pojo.User;
import com.mszlu.union.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.apache.dubbo.config.annotation.DubboReference;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
@Api(tags = "用户管理")
@RestController
@RequestMapping("user")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("findAll")
    @ApiOperation(value = "获取用户列表")
//    @PreAuthorize("hasAuthority('USER_FINDALL')")
    public List<User> findAll(){
        return userService.findAll();
    }

    @GetMapping("findAge")
//    @PreAuthorize("hasAuthority('USER_FINDAGE')")
    public List<User> findAge(){
        return userService.findAge();
    }

    @GetMapping("findById")
    @ApiOperation(value = "查询用户信息",notes = "根据id查询用户信息")
    @ApiImplicitParam(paramType = "get传参", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")
//    @PreAuthorize("hasRole('ADMIN')")
    public User findById(@RequestParam("id") Long id){
        return userService.findById(id);
    }

    @GetMapping("findPage")
    public List<User> findPage(@RequestParam("page") Integer page,
                               @RequestParam("pageSize") Integer pageSize){
        return userService.findPage(page,pageSize);
    }
    @GetMapping("save")
    public Long findAll(@RequestParam("name") String name){
        return userService.save(name);
    }

    @GetMapping("send")
    public String send(){
         userService.send();
         return "success";
    }
    //问注册中心 要服务提供方的地址
    //发起rpc调用
    //返回的数据 进行解析
    @DubboReference(version = "1.0.0")
    private DubboUserService dubboUserService;

    @GetMapping("dubbo")
    public String dubbo(){
        dubboUserService.save();
        return "success";
    }
}

1.5 springSecurity框架忽略swagger2的相关url

1
2
3
4
5
.antMatchers("/swagger-ui.html").permitAll()
               .antMatchers("/webjars/**").permitAll()
               .antMatchers("/swagger*/**").permitAll()
               .antMatchers("/v2/**").permitAll()
               .antMatchers("/csrf").permitAll()