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 1272434821@qq.com
 * @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

如果觉得我的文章对您有帮助,请予以打赏。您的支持将鼓励我继续创作!谢谢！