部标监控平台接口开发

swagger用于定义API文档。好处：

• 前后端分离开发

• API文档非常明确

• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller

• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）

• SpringBoot与Swagger的集成非常简单

1. pom.xml引入spring4all的swagger starter

    <groupId>com.spring4all</groupId>

    <artifactId>swagger-spring-boot-starter</artifactId>

    <version>1.6.0.RELEASE</version>

2. 以用户登录接口为例，创建baseinfo/user/api，在api包里创建LoginDTO用于接收客户端发送的账号和密码。@ApiModel是swagger描述Model信息的注解，@Data是lombok工具的注解，会自动生成getter和setter等让代码更简洁，@ApiModelProperty是swagger描述Model属性信息的注解，required=true表示此字段不能为空，@NotBlank用于校验字段不能为空。

@ApiModel("登录信息")
@Data
public class LoginDTO {

    @ApiModelProperty(value = "账号", required = true, position = 1)
    @NotBlank(message = "账号不能为空")
    private String account;

    @ApiModelProperty(value = "密码", required = true, position = 2)
    @NotBlank(message = "密码不能为空")
    private String password;
}

3. 创建baseinfo/user/controller的包，再创建接口类LoginController。这里普及一下jwt（json web token），前端登录成功后会得到token，之后与接口交互请求头带上token，后端会验证token的合法性。这里的例子为了简单就不再去数据库查询验证了。

@Api(tags = "登录接口")
@RestController
@RequestMapping("/api/v1/baseinfo/users")
@Slf4j
public class LoginController {

    @Value("${gnss.token.timeout}")
    private long tokenTimeout;

    @ApiOperation("登录")
    @PostMapping("/login")
    public ResultDTO<String> login(@ApiParam("登录信息") @Valid @RequestBody LoginDTO loginDTO) {
        log.info("登录,用户名:{},密码:{}", loginDTO.getAccount(), loginDTO.getPassword());
        AuthTokenDetails authTokenDetails = new AuthTokenDetails();
        authTokenDetails.setUserId(1L);
        authTokenDetails.setOrganizationId(1L);
        authTokenDetails.setRoleId(1L);
        authTokenDetails.setRoleType(RoleTypeEnum.ADMIN);
        authTokenDetails.setExpirationDate(new Date(System.currentTimeMillis() + tokenTimeout));
        String token = JwtUtils.generateToken(authTokenDetails);
        return new ResultDTO<>(token);
    }
}

所有的接口返回结果都用ResultDTO（分页的另外定义了DTO)

@ApiModel("统一响应结果")
@Data
public class ResultDTO<T> implements Serializable {

    private static final ResultDTO<?> EMPTY = new ResultDTO<>();

    @ApiModelProperty(value = "响应代码", position = 1)
    private int code = ResultCodeEnum.SUCCESS.getCode();

    @ApiModelProperty(value = "响应消息", position = 2)
    private String msg = ResultCodeEnum.SUCCESS.getDesc();

    @ApiModelProperty(value = "数据", position = 3)
    private T data;

    public ResultDTO() {
        super();
    }

    public ResultDTO(T data) {
        super();
        this.data = data;
    }

    public ResultDTO(Throwable e) {
        super();
        this.msg = e.getMessage();
        this.code = ResultCodeEnum.FAIL.getCode();
    }

    public ResultDTO(ResultCodeEnum resultCodeEnum, String msg) {
        super();
        this.code = resultCodeEnum.getCode();
        this.msg = msg;
    }

    @SuppressWarnings("unchecked")
    public static final <T> ResultDTO<T> empty() {
        return (ResultDTO<T>) EMPTY;
    }
}

4. 在resources/application.yml配置swagger信息：

spring:
  application:
    name: gnss-web
  profiles:
    active: test

  data:
    redis:
      repositories:
        enabled: false

server:
  servlet:
    context-path: /gnss-admin

gnss:
  token:
    #JWT超时时间7200000毫秒
    timeout: 7200000

swagger:
  enabled: true
  title: 北斗/GPS物联网监控平台
  description: GNSS Web
  version: 1.0.1.RELEASE
  contact:
    name: 梦幻
    url: http://www.gps-pro.cn
    wechat: 17158638841
  docket:
    command:
      title: 指令操作
      basePackage: com.gnss.web.command
    baseinfo:
      title: 基础信息
      basePackage: com.gnss.web.baseinfo

5. 启动类加上@EnableSwagger2Doc

@SpringBootApplication
@EnableWebMvc
@EnableCaching
@EnableSwagger2Doc
public class GnssWebApplication {
    public static void main(String[] args) {
        SpringApplication.run(GnssWebApplication.class, args);
    }
}

6. 启动GnssWebApplication，打开http://localhost:8090/gnss-admin/swagger-ui.html就可以测试接口了
   image.png

官方网站：http://www.gps-pro.cn
开源地址：https://github.com/gnss-pro
微信：17158638841 或扫描下图

image.png