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

- 日理万妓 2022-05-28 00:20 417阅读 0赞

**一、简介**

**(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][Swagger-ui]

Springfox地址为:[https://github.com/springfox/springfox][https_github.com_springfox_springfox]

**二、使用**

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

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

运行效果如下:

![20180328151336906][]

测试分页返回数据如下:

![20180328151511767][]

**三、Swagger常用注解**

API详细说明

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

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

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

与Controller注解并列使用。 属性配置：

在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中的方法并列使用。

属性配置：

<table> 
 <thead> 
  <tr> 
   <th style="text-align:left;"><span style="font-size:18px;">属性名称</span></th> 
   <th style="text-align:right;"><span style="font-size:18px;">备注</span></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><span style="font-size:18px;">value</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">url的路径值</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">tags</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">如果设置这个值、value的值会被覆盖</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">description</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">对api资源的描述</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">basePath</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">基本路径可以不配置</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">position</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">如果配置多个Api 想改变显示的顺序位置</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">produces</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">For example, "application/json, application/xml"</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">consumes</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">For example, "application/json, application/xml"</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">protocols</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">Possible values: http, https, ws, wss.</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">authorizations</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">高级特性认证时配置</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">hidden</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">配置为true 将在文档中隐藏</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">response</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">返回的对象</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">responseContainer</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">这些对象是有效的 "List", "Set" or "Map".，其他无效</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">httpMethod</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">code</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">http的状态码 默认 200</span></td> 
  </tr> 
  <tr> 
   <td><span style="font-size:18px;">extensions</span></td> 
   <td style="text-align:right;"><span style="font-size:18px;">扩展属性</span></td> 
  </tr> 
 </tbody> 
</table>

在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中的方法并列使用。  
属性配置：

在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中的方法并列使用。 属性配置：

在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中的方法并列使用。 属性配置：

在SpringMvc中的配置如下：

**6. ResponseHeader**

响应头设置，使用方法

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

与Controller中的方法并列使用。 属性配置：

<table style="border-collapse:collapse;border-spacing:0px;width:620px;margin-bottom:20px;border-top:1px solid rgb(221,221,221);border-right:1px solid rgb(221,221,221);border-bottom:1px solid rgb(221,221,221);border-left:none;color:rgb(47,47,47);font-size:16px;"> 
 <thead> 
  <tr> 
   <th style="padding:8px;text-align:left;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">属性名称</th> 
   <th style="padding:8px;text-align:right;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">name</td> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;text-align:right;">响应头名称</td> 
  </tr> 
  <tr> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">description</td> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;text-align:right;">头描述</td> 
  </tr> 
  <tr> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">response</td> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;text-align:right;">默认响应类 Void</td> 
  </tr> 
  <tr> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;">responseContainer</td> 
   <td style="padding:8px;border:1px solid rgb(221,221,221);line-height:20px;vertical-align:middle;text-align:right;">参考ApiOperation中配置</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

**7.@ApiImplicitParam**

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

<table style="border-collapse:collapse;width:780px;text-align:center;margin-bottom:24px;color:rgb(69,69,69);font-size:16px;"> 
 <thead> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <th style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;background-color:rgb(239,243,245);">属性</th> 
   <th align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;background-color:rgb(239,243,245);">取值</th> 
   <th align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;background-color:rgb(239,243,245);">作用</th> 
  </tr> 
 </thead> 
 <tbody style="border:0px;"> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">paramType</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">查询参数类型</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">path</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">以地址的形式提交数据</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">query</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">body</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">header</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">参数在request headers 里边提交</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">form</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">dataType</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">Long</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">String</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">name</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">接收参数名</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">value</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">接收参数的意义描述</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">required</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">参数是否必填</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">true</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">必填</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);background-color:rgb(247,247,247);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">false</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">非必填</td> 
  </tr> 
  <tr style="border-width:1px 0px 0px;border-top-style:solid;border-top-color:rgb(221,221,221);"> 
   <td style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">defaultValue</td> 
   <td align="center" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">&nbsp;</td> 
   <td align="right" style="font-size:14px;color:rgb(79,79,79);line-height:22px;border:1px solid rgb(221,221,221);padding:8px;text-align:left;vertical-align:middle;">默认值</td> 
  </tr> 
 </tbody> 
</table>

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][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了。在完成生成之后，可以直接通过浏览器来看查看，你就能看到类似下图的静态部署结果：

![20180328154033358][]

完整示例如下:

GitHub: [https://github.com/fendo8888/mybatis-plus][https_github.com_fendo8888_mybatis-plus]

CSDN: [https://download.csdn.net/download/u011781521/10313693][https_download.csdn.net_download_u011781521_10313693]

参考文章:

[http://blog.didispace.com/swagger2markup-asciidoc/][http_blog.didispace.com_swagger2markup-asciidoc]

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

[https://my.oschina.net/dlam/blog/808315][https_my.oschina.net_dlam_blog_808315]

[Swagger-tools]: https://github.com/apigee-127/swagger-tools
[Swagger-core]: https://github.com/swagger-api/swagger-core
[Swagger-js]: https://github.com/swagger-api/swagger-js
[Swagger-node-express]: https://github.com/swagger-api/swagger-node
[Swagger-ui]: https://github.com/swagger-api/swagger-ui
[Swagger-codegen]: https://github.com/swagger-api/swagger-codegen
[Swagger-editor]: https://github.com/swagger-api/swagger-editor
[https_github.com_springfox_springfox]: https://github.com/springfox/springfox
[20180328151336906]: /images/20220528/be470bb8d211481d834412458cc44a3f.png
[20180328151511767]: /images/20220528/3dbceda9a52642beb25f9f1a20cc5ea5.png
[https_github.com_Swagger2Markup_swagger2markup]: https://github.com/Swagger2Markup/swagger2markup
[20180328154033358]: /images/20220528/3e28c6d4bd3a4ed693ee360b9e20da3f.png
[https_github.com_fendo8888_mybatis-plus]: https://github.com/fendo8888/mybatis-plus
[https_download.csdn.net_download_u011781521_10313693]: https://download.csdn.net/download/u011781521/10313693
[http_blog.didispace.com_swagger2markup-asciidoc]: http://blog.didispace.com/swagger2markup-asciidoc/
[https_leongfeng.github.io_2017_02_20_springboot-springfox-swagger2markup-spring-restdoc]: https://leongfeng.github.io/2017/02/20/springboot-springfox-swagger2markup-spring-restdoc/
[https_my.oschina.net_dlam_blog_808315]: https://my.oschina.net/dlam/blog/808315