swagger用于定義API文檔。好處：

• 前后端分離開發(fā)

• API文檔非常明確

• 測試的時候不需要再使用URL輸入瀏覽器的方式來訪問Controller

• 傳統(tǒng)的輸入URL的測試方式對于post請求的傳參比較麻煩（當(dāng)然，可以使用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. 以用戶登錄接口為例，創(chuàng)建baseinfo/user/api，在api包里創(chuàng)建LoginDTO用于接收客戶端發(fā)送的賬號和密碼。@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. 創(chuàng)建baseinfo/user/controller的包，再創(chuàng)建接口類LoginController。這里普及一下jwt（json web token），前端登錄成功后會得到token，之后與接口交互請求頭帶上token，后端會驗證token的合法性。這里的例子為了簡單就不再去數(shù)據(jù)庫查詢驗證了。

@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);
    }
}

所有的接口返回結(jié)果都用ResultDTO（分頁的另外定義了DTO)

@ApiModel("統(tǒng)一響應(yīng)結(jié)果")
@Data
public class ResultDTO<T> implements Serializable {

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

    @ApiModelProperty(value = "響應(yīng)代碼", position = 1)
    private int code = ResultCodeEnum.SUCCESS.getCode();

    @ApiModelProperty(value = "響應(yīng)消息", position = 2)
    private String msg = ResultCodeEnum.SUCCESS.getDesc();

    @ApiModelProperty(value = "數(shù)據(jù)", 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物聯(lián)網(wǎng)監(jiān)控平臺
  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: 基礎(chǔ)信息
      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

官方網(wǎng)站：http://www.gps-pro.cn
開源地址：https://github.com/gnss-pro
微信：17158638841 或掃描下圖

image.png