Spring Boot 系列教程9-swagger-前后端分離后的標准

前后端分離的必要

• 現在的趨勢發展，需要把前后端開發和部署做到真正的分離
• 做前端的誰也不想用Maven或者Gradle作為構建工具
• 做后端的誰也不想要用Grunt或者Gulp作為構建工具

前后端需要通過接口來協作

• 可能是JSON格式的RESTFul的接口
• 可能是XML的接口
• 重點是后台只負責數據的提供和處理，而完全不處理展現
• 而前端則負責拿到數據，組織數據並開始展現的工作

Swagger

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

Swagger API顯示效果

項目圖片

pom.xml

<!-- Swagger2強大RESTful API文檔 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

Swagger2

package com.jege.spring.boot.swagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
  // http://localhost:8080/swagger-ui.html
  // Swagger2默認將所有的Controller中的RequestMapping方法都會暴露，
  // 然而在實際開發中，我們並不一定需要把所有API都提現在文檔中查看，這種情況下，使用注解
  // @ApiIgnore來解決，如果應用在Controller范圍上，則當前Controller中的所有方法都會被忽略，
  // 如果應用在方法上，則對應用的方法忽略暴露API

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
    .apis(RequestHandlerSelectors.basePackage("com.jege.spring.boot.controller")).paths(PathSelectors.any())
    .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("je-ge的漿糊").description("je-ge的漿糊")
    .termsOfServiceUrl("http://blog.csdn.net/je_ge").contact("je-ge").version("1.0").build();
  }

}

UserController

package com.jege.spring.boot.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.jege.spring.boot.data.jpa.entity.User;
import com.jege.spring.boot.data.jpa.repository.UserRepository;
import com.jege.spring.boot.json.AjaxResult;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/** * @author JE哥 * @email [e-mail] * @description:用戶CRUD操作 */
@RestController
@RequestMapping("/user")
public class UserController {

  @Autowired
  private UserRepository userRepository;

  // 顯示用戶列表
  @RequestMapping("/list")
  public String list() {
    return "user";
  }

  // 顯示用戶json數據
  @ApiOperation(value = "獲取用戶列表，支持分頁", notes = "json方法獲取用戶列表")
  @ApiImplicitParams({ @ApiImplicitParam(name = "page", value = "當前頁碼", required = true, dataType = "int"),
      @ApiImplicitParam(name = "rows", value = "每頁條數", required = true, dataType = "int") })
  @RequestMapping("/json")
  @ResponseBody
  public Map<String, Object> json(@RequestParam(name = "page", defaultValue = "1") int page,
      @RequestParam(name = "rows", defaultValue = "10") int rows) {
    Pageable pageable = new PageRequest(page - 1, rows);
    return findEasyUidata(userRepository.findAll(pageable));
  }

  private <T> Map<String, Object> findEasyUidata(Page<T> page) {
    Map<String, Object> map = new HashMap<String, Object>();
    map.put("rows", page.getContent());
    map.put("total", page.getTotalElements());
    return map;
  }

  // 處理保存
  @ApiOperation(value = "保存用戶", notes = "根據User對象操作用戶")
  @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
  @RequestMapping("/save")
  @ResponseBody
  public AjaxResult save(User user) {
    userRepository.save(user);
    return new AjaxResult().success();
  }

  // 處理刪除
  @ApiOperation(value = "刪除用戶", notes = "根據url的id來指定刪除對象")
  @ApiImplicitParam(name = "id", value = "用戶id", required = true, dataType = "Long")
  @RequestMapping("/delete")
  @ResponseBody
  public AjaxResult delete(Long id) {
    userRepository.delete(id);
    return new AjaxResult().success();
  }
}

訪問地址swagger的地址

http://localhost:8080/swagger-ui.html

其他關聯代碼

• Spring Boot 系列教程7-EasyUI-datagrid
  http://blog.csdn.net/je_ge/article/details/53365189
• Spring Boot 系列教程5-熱部署-devtools模塊
  http://blog.csdn.net/je_ge/article/details/53326525
• Spring Boot 系列教程2-Data JPA
  http://blog.csdn.net/je_ge/article/details/53294949

源碼地址

https://github.com/je-ge/spring-boot

如果覺得我的文章對您有幫助,請予以打賞。您的支持將鼓勵我繼續創作!謝謝！