MyBatis-Plus系列(二)--MyBatis-Plus结合Swagger使用

一、简介


(A)、介绍

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口,可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger消除了调用服务时可能会有的猜测。


Swagger是一组开源项目,其中主要要项目如下:


Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
Swagger-core: 用于、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

Swagger-editor:可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger JSON描述,并用于所有Swagger工具(代码生成、文档等等)中。


除了Swagger项目自身支持的Java、Scala和JavaScript语言,Swagger社区中还提供了很多支持其他语言的第三方工具,覆盖了Clojure、ColdFusion / CFML、Eiffel、Go、Groovy、.Net、Perl、PHP、Python、Ruby等各种编程语言。


SwaggerAPI文档工具可以满足下列需求:


●支持API自动生成同步的在线文档
这些文档可用于项目内部API审核
方便测试人员了解API
这些文档可作为客户产品文档的一部分进行发布
支持API规范生成代码,生成的客户端和服务器端骨架代码可以加速开发和测试速度


(B)、swagger-ui 和 springfox-swagger-ui 的关系是?


Swagger Spec 是一个规范。
Swagger Api 是 Swagger Spec 规范 的一个实现,它支持 jax-rs, restlet, jersey 等等。
Springfox libraries 是 Swagger Spec 规范 的另一个实现,专注于 spring 生态系统。
Swagger.js and Swagger-ui 是 javascript 的客户端库,能消费该规范。
springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ,使得 Spring 服务可以提供服务。

总结为:

Swagger 是一种规范。
Springfox-swagger 是基于 Spring 生态系统的该规范的实现。
Springfox-swagger-ui 是对 swagger-ui 的封装,使得其可以使用 Spring 的服务。


Swagger地址为:https://github.com/swagger-api/swagger-ui

Springfox地址为:https://github.com/springfox/springfox


二、使用


首先引入Maven依赖,这里用的是最新的2.8版本:

<!--Swagger UI-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.8.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.8.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-bean-validators</artifactId>
	<version>2.8.0</version>
</dependency>

然后创建Swagger配置类:
/**
 * projectName: xxxx
 * fileName: SwaggerConfig.java
 * packageName: com.xxx.common.config
 * date: 2018-02-01 1:14
 * copyright(c) 2017-2020 xxx公司
 */
package com.fendo.mybatis.plus.config;

import springfox.documentation.service.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.annotations.ApiIgnore;
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;

/**
 * @version: V1.0
 * @author: fendo
 * @className: SwaggerConfig
 * @packageName: com.fendo.mybatis.plus.config
 * @description: Swagger配置文件
 * @data: 2018-02-01 1:14
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public static final String VERSION = "1.0.0";
    public static final String AUTHOR = "fendo";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.groupName("基础模块")
                .select()
                //加了ApiOperation注解的方法,生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.fendo.mybatis.plus"))  
                //可以根据url路径设置哪些请求加入文档,忽略哪些请求
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(ApiIgnore.class)
                .enableUrlTemplating(true);
    }

    @Bean
    public Docket createMonitorRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("权限模块")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.fendo.mybatis.plus"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档的标题
                .title("API文档")  
                //设置文档的描述
                .description("mybatis-plus项目API文档") 
                .termsOfServiceUrl("http://blog.csdn.net/u011781521?viewmode=contents")
                //设置文档的版本信息
                .version(VERSION)
                //作者信息
                .contact(new Contact(AUTHOR, "http://blog.csdn.net/u011781521", "2312892206@qq.com"))
                //设置文档的License信息
                .termsOfServiceUrl("http://blog.csdn.net/u011781521?viewmode=contents") 
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

}

然后创建实体类,并添加注解:
/**
 * projectName: mybatis-plus
 * fileName: UserEntity.java
 * packageName: com.fendo.mybatis.plus.entity.enums
 * date: 2018-03-24 18:11
 * copyright(c) 2017-2020 xxx公司
 */
package com.fendo.mybatis.plus.entity;

import com.baomidou.mybatisplus.annotations.TableName;
import com.fendo.mybatis.plus.common.persistent.BaseEntity;
import com.fendo.mybatis.plus.entity.enums.AgeEnum;
import com.fendo.mybatis.plus.entity.enums.GenderEnum;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import javax.validation.constraints.Max;
import javax.validation.constraints.Min;

/**
 * @version: V1.0
 * @author: fendo
 * @className: UserEntity
 * @packageName: com.fendo.mybatis.plus.entity.enums
 * @description: 用户类
 * @data: 2018-03-24 18:11
 **/
@TableName("user")
@ApiModel(value="User对象",description="用户信息")
public class UserEntity extends BaseEntity<UserEntity> {

    /**
     * 名称
     */
    @ApiModelProperty(value = "用户姓名",name="name",example="fendo")
    private String name;
    /**
     * 年龄
     */
    @ApiModelProperty(value = "用户年龄",name="age",example="2")
    @Max(150)
    @Min(1)
    private AgeEnum age;

    /**
     * 性别
     */
    @ApiModelProperty(value = "用户性别",name="sex",example="1")
    private GenderEnum sex;


    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public AgeEnum getAge() {
        return age;
    }

    public void setAge(AgeEnum age) {
        this.age = age;
    }

    public GenderEnum getSex() {
        return sex;
    }

    public void setSex(GenderEnum sex) {
        this.sex = sex;
    }

    public UserEntity() {
    }

    public UserEntity(String name, AgeEnum age, GenderEnum sex) {
        this.name = name;
        this.age = age;
        this.sex = sex;
    }

    public UserEntity(String id, String name, AgeEnum age, GenderEnum sex) {
        this.setId(id);
        this.name = name;
        this.age = age;
        this.sex = sex;
    }


}

然后创建分页封装类:

package com.fendo.mybatis.plus.common.utils;

import com.baomidou.mybatisplus.plugins.Page;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.util.List;

/**
 * @version: V1.0
 * @author: fendo
 * @className: CustomPage
 * @packageName: com.fendo.mybatis.plus.common.utils
 * @description: 自定义分页数据
 * @data: 2018-03-27 9:23
 **/
@ApiModel
public class CustomPage<T> {
	
	//当前页数
	@ApiModelProperty(value = "当前页数")
    private int pageNo;

    //每页显示数量
	@ApiModelProperty(value = "每页显示数量")
    private int pageSize;

    @ApiModelProperty(value = "总条数")
    private int totalRecord;

    //数据列表
    @ApiModelProperty(value = "数据列表")
    private List<T> parameterType;

    //总页数
    @ApiModelProperty(value = "总页数")
    private int totalPage;

    //排序字段
    @ApiModelProperty(value = "排序字段")
    private String orderByField;

    //是否升序
    @ApiModelProperty(value = "是否升序")
    private boolean isAsc;

	public int getPageNo() {
		return pageNo;
	}

	public void setPageNo(int pageNo) {
		this.pageNo = pageNo;
	}

	public int getPageSize() {
		return pageSize;
	}

	public void setPageSize(int pageSize) {
		this.pageSize = pageSize;
	}

	public int getTotalRecord() {
		return totalRecord;
	}

	public void setTotalRecord(int totalRecord) {
		this.totalRecord = totalRecord;
	}

	public List<T> getParameterType() {
		return parameterType;
	}

	public void setParameterType(List<T> parameterType) {
		this.parameterType = parameterType;
	}

	public int getTotalPage() {
		return totalPage;
	}

	public void setTotalPage(int totalPage) {
		this.totalPage = totalPage;
	}

	public String getOrderByField() {
		return orderByField;
	}

	public void setOrderByField(String orderByField) {
		this.orderByField = orderByField;
	}

	public boolean isAsc() {
		return isAsc;
	}

	public void setAsc(boolean isAsc) {
		this.isAsc = isAsc;
	}
    
	public CustomPage(){}

    @SuppressWarnings("deprecation")
	public CustomPage(Page<T> page){
        this.pageNo = page.getCurrent();
        this.pageSize = page.getSize();
        this.totalRecord = (int) page.getTotal();
        this.parameterType = page.getRecords();
        this.totalPage = (int) page.getPages();
        this.orderByField = page.getOrderByField();
        this.isAsc = page.isAsc();
    }

}

统一返回数据类:

/**
 * projectName: mybatis-plus
 * fileName: ResultData.java
 * packageName: com.fendo.mybatis.plus.common.utils
 * date: 2018-03-27 10:38
 * copyright(c) 2017-2020 xxx公司
 */
package com.fendo.mybatis.plus.common.utils;

import com.fendo.mybatis.plus.entity.UserEntity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**
 * @version: V1.0
 * @author: fendo
 * @className: ResultData
 * @packageName: com.fendo.mybatis.plus.common.utils
 * @description: 返回数据
 * @data: 2018-03-27 10:38
 **/
@ApiModel
public class ResultData <T> implements Serializable {

    private static final long serialVersionUID = -7424426799887924229L;

    @ApiModelProperty(value = "错误码")
    private String code;

    @ApiModelProperty(value = "数据对象")
    private T data;

    @ApiModelProperty(value = "错误码描述")
    private String message;

    public ResultData(CustomPage<UserEntity> customPage) {
    }

    public ResultData(String code, String message) {
        this.code = code;
        this.message = message;
    }

    public ResultData(SimpleCode simpleCode) {
        this.code = simpleCode.getCode();
        this.message = simpleCode.getMessage();
    }



    public ResultData(String code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public ResultData(SimpleCode simpleCode, T data) {
        this.code = simpleCode.getCode();
        this.message = simpleCode.getMessage();
        this.data = data;
    }

    public ResultData(Boolean falg, T data) {
        if(falg){
            this.code = SimpleCode.SUCCESS.getCode();
            this.message = SimpleCode.SUCCESS.getMessage();
            this.data =  data;
        }else {
            this.code = SimpleCode.ERROR.getCode();
            this.message = SimpleCode.ERROR.getMessage();
            this.data =  data;
        }
    }


    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    @Override
    public String toString() {
        return "JSONResult [code=" + code + ", data=" + data + ", message="
                + message + "]";
    }
}
创建Controller类:
/**
 * projectName: mybatis-plus
 * fileName: UserController.java
 * packageName: com.fendo.mybatis.plus.controller
 * date: 2018-03-27 10:26
 * copyright(c) 2017-2020 xxx公司
 */
package com.fendo.mybatis.plus.controller;

import com.baomidou.mybatisplus.plugins.Page;
import com.fendo.mybatis.plus.common.utils.*;
import com.fendo.mybatis.plus.common.web.BaseController;
import com.fendo.mybatis.plus.entity.UserEntity;
import com.fendo.mybatis.plus.entity.enums.AgeEnum;
import com.fendo.mybatis.plus.entity.enums.GenderEnum;
import com.fendo.mybatis.plus.request.UserRequest;
import com.fendo.mybatis.plus.service.UserService;
import io.swagger.annotations.*;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
import java.util.List;
import java.util.Map;

/**
 * @version: V1.0
 * @author: fendo
 * @className: UserController
 * @packageName: com.fendo.mybatis.plus.controller
 * @description: 用户Controller
 * @data: 2018-03-27 10:26
 **/
@Controller
@RequestMapping("/user")
@Api(value = "/user", description = "用户操作接口")
@Validated
public class UserController extends BaseController{

    @Autowired
    protected UserService userService;

    /**
     * 用户新增与更新
     * @param data
     * @return
     */
    @PostMapping("/save")
    @ResponseBody
    @ApiOperation(value = "更新用户信息", notes = "更新或者保存用户信息")
    @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
    public ResultData<CustomPage<UserEntity>> save(@RequestBody @ApiParam(name="用户对象",value="传入JSON格式",required=true) UserRequest data) {
        ResultData<CustomPage<UserEntity>> result = null;
        CustomPage<UserEntity> customPage = null;
        if(validates(validator, data)!=null){
            result = new ResultData<CustomPage<UserEntity>>(SimpleCode.ERROR.getCode(), validates(validator, data));
        }
        UserEntity userEntity = new UserEntity();
        BeanUtils.copyProperties(data,userEntity);
        if(StringUtils.isNotEmpty(userEntity.getId())){
            userEntity.updateById();
        }else {
            userEntity.insert();
        }
        Page<UserEntity> userEntityPage = userEntity.selectPage(new Page<UserEntity>(0, 12), null);
        customPage = new CustomPage<UserEntity>(userEntityPage);
        result = new ResultData<CustomPage<UserEntity>>(SimpleCode.SUCCESS, customPage);
        return result;
    }

    /**
     * 删除用户
     * @param id
     * @return
     */
    @ApiOperation(value = "删除用户", notes = "通过用户id删除用户", httpMethod = "GET")
    @ApiResponses({ @ApiResponse(code = 200, message = "操作成功"),
            @ApiResponse(code = 500, message = "服务器内部异常"),
            @ApiResponse(code = 405, message = "权限不足") })
    @GetMapping("/delete")
    @ResponseBody
    public ResultData<String> delete(@NotEmpty(message = "用户ID不能为空") @ApiParam(value = "用户ID)", required = true) @RequestParam String id){
        ResultData<String> result;
        UserEntity userEntity = new UserEntity();
        userEntity.setId(id);
        result = new ResultData(userEntity.deleteById(),"用户删除");
        return result;
    }

    /**
     * 根据用户ID获取用户
     * @param id
     * @return
     */
    @GetMapping("/get")
    @ResponseBody
    @ApiOperation(value = "获取用户信息", notes = "更新ID获取用户信息")
    public ResultData<UserEntity> get(@NotEmpty(message = "用户ID不能为空") @ApiParam(value = "用户ID)", required = true) @RequestParam String id){
        UserEntity userEntity = userService.selectById(id);
        return new ResultData<UserEntity>(SimpleCode.SUCCESS,userEntity);
    }

    /**
     * 参数模式分页
     * @param page
     * @return
     */
    @GetMapping("/list")
    @ResponseBody
    @ApiImplicitParams({
            @ApiImplicitParam(name = "size", value = "一页大小", required = false, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "current", value = "当前页码", required = false, dataType = "String", paramType = "query"),
    })
    @ApiOperation(value = "自带分页", notes = "分页获取数据")
    public ResultData<CustomPage<UserEntity>> lis(Page page) {
        CustomPage<UserEntity> customPage = new CustomPage<UserEntity>(userService.selectPage(page));
        return  new ResultData<CustomPage<UserEntity>>(SimpleCode.SUCCESS, customPage);
    }


    /**
     * 分页
     * @param frontPage
     * @return
     */
    @PostMapping("/page")
    @ResponseBody
    @ApiOperation(value = "自定义分页", notes = "分页获取数据")
    public ResultData<CustomPage<Map<String,Object>>> page(@ApiParam(required = false, value = "分页参数") @RequestBody(required=false) FrontPage<UserRequest> frontPage) {
        CustomPage<Map<String,Object>> customPage = new CustomPage<Map<String,Object>>(userService.getPage(frontPage.getPagePlus(),frontPage.getParam()));
        return  new ResultData<CustomPage<Map<String,Object>>>(SimpleCode.SUCCESS, customPage);
    }

}

运行效果如下:


测试分页返回数据如下:



三、Swagger常用注解


API详细说明

作用范围API使用位置
对象属性@ApiModelProperty用在出入参数对象的字段上
协议集描述@Api用于controller类上
协议描述@ApiOperation用在controller的方法上
Response集@ApiResponses用在controller的方法上
Response@ApiResponse用在 @ApiResponses里边
非对象参数集@ApiImplicitParams用在controller的方法上
非对象参数描述@ApiImplicitParam用在@ApiImplicitParams的方法里边
描述返回对象的意义@ApiModel用在返回对象类上

忽略某类/方法/参数的文档     @ApiIgnore                     用在类/方法/参数


1. api标记

Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式 

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置:
属性名称备注
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
description对api资源的描述
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, "application/json, application/xml"
consumesFor example, "application/json, application/xml"
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏


在SpringMvc中的配置如下:

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {

}

2. ApiOperation标记

ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:
@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

与Controller中的方法并列使用。


属性配置:
属性名称备注
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
description对api资源的描述
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, "application/json, application/xml"
consumesFor example, "application/json, application/xml"
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏
response返回的对象
responseContainer这些对象是有效的 "List", "Set" or "Map".,其他无效
httpMethod"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
codehttp的状态码 默认 200
extensions扩展属性

在SpringMvc中的配置如下:
@RequestMapping(value = "/order/{orderId}", method = GET)
  @ApiOperation(
      value = "Find purchase order by ID",
      notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
      response = Order.class,
      tags = { "Pet Store" })
   public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }

3. ApiParam标记

ApiParam请求属性,使用方式:

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)
与Controller中的方法并列使用。
属性配置:

属性名称备注
name属性名称
value属性值
defaultValue默认属性值
allowableValues可以不配置
required是否属性必填
access不过多描述
allowMultiple默认为false
hidden隐藏该属性
example举例子

在SpringMvc中的配置如下:
public ResponseEntity<Order> getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)

4. ApiResponse

ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置:
属性名称备注
codehttp的状态码
message描述
response默认响应类 Void
reference参考ApiOperation中配置
responseHeaders参考 ResponseHeader 属性配置说明
responseContainer参考ApiOperation中配置

在SpringMvc中的配置如下:
@RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

5. ApiResponses

ApiResponses:响应集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置:
属性名称备注
value多个ApiResponse配置
在SpringMvc中的配置如下:
@RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

6. ResponseHeader

响应头设置,使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置:
属性名称备注
name响应头名称
description头描述
response默认响应类 Void
responseContainer参考ApiOperation中配置
在SpringMvc中的配置如下:
@ApiModel(description = "群组")

7.@ApiImplicitParam

用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

属性取值作用
paramType 查询参数类型
 path以地址的形式提交数据
 query直接跟参数完成自动映射赋值
 body以流的形式提交 仅支持POST
 header参数在request headers 里边提交
 form以form表单的形式提交 仅支持POST
dataType 参数的数据类型 只作为标志说明,并没有实际验证
 Long 
 String 
name 接收参数名
value 接收参数的意义描述
required 参数是否必填
 true必填
 false非必填
defaultValue 默认值
paramType 示例详解

1.Path
@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

@PathVariable(name = "id") Long id

2.Body
@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
@RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

@RequestBody MessageParam param

提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)

3.Header
@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 

String idstr = request.getHeader("id");
if (StringUtils.isNumeric(idstr)) {
	id = Long.parseLong(idstr);
}

4.Form
@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
@RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)


8. 其他

@ApiImplicitParams:用在方法上包含一组参数说明;
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    ●paramType:参数放在哪个地方
    ●name:参数代表的含义
    ●value:参数名称
    ●dataType: 参数类型,有String/int,无用
    ●required : 是否必要
    ●defaultValue:参数的默认值
@ApiResponses:用于表示一组响应;
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息;
    ●code: 响应码(int型),可自定义
    ●message:状态码对应的响应信息
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
@ApiModelProperty:描述一个model的属性。

四、使用Swagger2Markup实现API文档的静态部署

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。

项目主页: https://github.com/Swagger2Markup/swagger2markup

4.1、首先要生成AsciiDoc

生成AsciiDoc的方式有两种:

4.1.1、通过Java代码来生成

第一步:编辑pom.xml增加需要使用的相关依赖和仓库
<dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
</dependency>

第二步:编写一个单元测试用例来生成执行生成文档的代码
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }

}

在执行了上面的测试用例之后,我们就能在当前项目的src目录下获得如下内容:
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc

生成出了4个不同的静态文件。

4.1.2、通过Maven插件来生成

swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式,完全可以通过在pom.xml中增加如下插件来完成静态内容的生成。
<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

4.2、生成HTML

完成了从Swagger文档配置文件到AsciiDoc的源文件转换之后,就是如何将AsciiDoc转换成可部署的HTML内容了。引入一个Maven插件来完成。
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
   	    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
   	    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
   	    <backend>html</backend>
   	    <sourceHighlighter>coderay</sourceHighlighter>
   	    <attributes>
            <toc>left</toc>
  	    </attributes>
  	</configuration>
</plugin>

执行该插件的
mvn asciidoctor:process-asciidoc
命令之后,就能在src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成之后,可以直接通过浏览器来看查看,你就能看到类似下图的静态部署结果:




完整示例如下:



参考文章:

http://blog.didispace.com/swagger2markup-asciidoc/

https://leongfeng.github.io/2017/02/20/springboot-springfox-swagger2markup-spring-restdoc/

https://my.oschina.net/dlam/blog/808315

  • 5
    点赞
  • 19
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Spring Boot和MyBatis-Plus是两个流行的Java开发框架。Spring Boot是一个用于简化和加速Java应用程序开发的框架,而MyBatis-PlusMyBatis的增强版,提供了更多的特性和功能。 使用Spring Boot2和MyBatis-Plus的组合,能够使开发过程更加高效和简便。Spring Boot2已经集成了很多常用的配置和功能,例如自动配置、快速启动器和监控等。这些功能使得开发者可以更加专注于业务逻辑而不用过多关注繁琐的配置。 而MyBatis-Plus提供了一系列强大且易于使用的功能,例如代码生成器、分页查询、逻辑删除和性能优化等。代码生成器能够帮助开发者快速生成数据库表对应的实体类、Mapper接口以及XML映射文件,大大提高了开发效率。分页查询和逻辑删除功能使得数据操作更加方便和灵活。另外,MyBatis-Plus对SQL语句进行了优化,能够提升数据库查询的性能。 使用Spring Boot2和MyBatis-Plus的组合还能够更好地兼容其他常用的开发工具和框架,例如Spring Security和Swagger等。Spring Security提供了安全认证和授权的功能,能够保护应用程序的安全性。Swagger可以生成API文档,并提供了一个用户友好的UI界面,方便开发者进行接口测试和调试。 总之,Spring Boot2和MyBatis-Plus的组合能够提高开发效率、简化配置、优化性能并提供额外的功能。对于Java开发者来说,这是一个非常不错且受欢迎的选择。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值