【Spring Boot】2.Swagger API

浅浅的花香味﹌ 2022-05-18 07:26 193阅读 0赞

**目录**

一、Swagger介绍

二、技术与IDE

三、具体应用

四、启动应用程序访问url

五、返回结果

六、API注解详情

--------------------

## 一、Swagger介绍 ##

swagger用于定义API文档，返回数据格式是json，用的是restful风格。

优点：

1.  前后端分离开发
2.  API文档非常明确
3.  测试的时候不需要再使用URL输入浏览器的方式来访问Controller
4.  传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
5.  spring boot与swagger的集成简单

spring boot中使用swagger2构建RESTful APIs

![70][]

## 二、技术与IDE ##

spring boot

IntelliJ IDEA

maven

swagger

## 三、具体应用 ##

ContentColumnController.java

package com.enterprisename.xserver.saas.basic.api.content;
    
    import com.enterprisename.xserver.baas.utilities.error.ErrCodeConstant;
    import com.enterprisename.xserver.baas.utilities.error.ErrMsgConstant;
    import com.enterprisename.xserver.baas.utilities.exception.CustomException;
    import com.enterprisename.xserver.baas.utilities.tools.validator.ValidatorUtils;
    import com.enterprisename.xserver.baas.utilities.tools.validator.groups.AddGroup;
    import com.enterprisename.xserver.baas.utilities.tools.validator.groups.UpdateGroup;
    import com.enterprisename.xserver.saas.basic.entity.content.ContentColumn;
    import com.enterprisename.xserver.saas.basic.service.content.ContentColumnService;
    import com.enterprisename.xserver.saas.common.account.entity.response.ResponseData;
    import com.enterprisename.xserver.saas.common.shiro.jwt.JwtTokenUtil;
    import io.swagger.annotations.*;
    import org.apache.commons.beanutils.ConvertUtils;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    import javax.servlet.http.HttpServletRequest;
    import java.util.HashMap;
    import java.util.Map;
    
    @Api(tags = "ContentColumn",description = "内容栏目接口")
    @RestController
    @RequestMapping(value = "/contentColumn")
    @ApiResponses({
            @ApiResponse(code = ErrCodeConstant.ERR_INVALID_INPUT_PARAM, message = ErrMsgConstant.MSG_INVALID_INPUT_PARAM),
            @ApiResponse(code = ErrCodeConstant.ERR_NO_AUTHENTICATE, message = ErrMsgConstant.MSG_NO_AUTHENTICATE),
            @ApiResponse(code = ErrCodeConstant.ERR_NO_AUTHORIZE, message = ErrMsgConstant.MSG_NO_AUTHORIZE),
            @ApiResponse(code = ErrCodeConstant.ERR_INVALID_TOKEN, message = ErrMsgConstant.MSG_INVALID_TOKEN)
    })
    public class ContentColumnController {
        @Autowired
        private ContentColumnService contentColumnService;
        @Autowired
        private JwtTokenUtil jwtTokenUtil;
    
        /**
         * 创建内容栏目
         * @param contentColumn
         * @return
         */
        @ApiOperation(value = "创建内容栏目", httpMethod = "POST", notes = "创建结果")
        @RequestMapping(value = "/create",method = RequestMethod.POST)
        @ApiImplicitParams({
                @ApiImplicitParam(name = "groupId",value = "所属group",required = true,dataType = "Long", paramType = "query"),
                @ApiImplicitParam(name = "parent",value = "父级栏目",required = true,dataType = "String", paramType = "query"),
                @ApiImplicitParam(name = "colName",value = "栏目名称",required = true,dataType = "String", paramType = "query")
        })
        @ApiResponses({
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_ADD_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_ADD_FAILED),
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_ALREADY_EXIST, message = ErrMsgConstant.MSG_CONTENTCOLUMN_ALREADY_EXIST),
        })
        public ResponseData create(@RequestBody ContentColumn contentColumn, HttpServletRequest request){
            ValidatorUtils.validateEntity(contentColumn,AddGroup.class);
            Long uid=getUuid(request);
            return contentColumnService.createContentColumn(contentColumn,uid);
        }
    
        /**
         * 更新内容栏目
         * @param contentColumn
         * @return
         */
        @ApiOperation(value = "更新内容栏目", httpMethod = "POST", notes = "更新结果")
        @RequestMapping(value = "/update/{uuid}",method = RequestMethod.POST)
        @ApiImplicitParams({
                @ApiImplicitParam(name = "uuid", value = "内容栏目id", required = true, dataType = "Long", paramType = "query")
        })
        @ApiResponses({
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_UPDATE_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_UPDATE_FAILED),
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_INVALID, message = ErrMsgConstant.MSG_CONTENTCOLUMN_INVALID),
        })
        public ResponseData update(@RequestBody ContentColumn contentColumn,HttpServletRequest request,@PathVariable("uuid") String uuid){
            contentColumn.setUuid(Long.parseLong(uuid));
            ValidatorUtils.validateEntity(contentColumn, UpdateGroup.class);
            Long uid = getUuid(request);
            return contentColumnService.updateContentColumnInfo(contentColumn,uid);
        }
    
        /**
         * 删除内容栏目
         */
        @ApiOperation(value = "删除内容栏目", httpMethod = "POST", notes = "删除结果")
        @RequestMapping(value = "/delete", method = RequestMethod.POST)
        @ApiImplicitParams({
                @ApiImplicitParam(name="contentColumnIds",value="内容栏目id集合",required = true,dataType = "Long[]",paramType = "query")
        })
        @ApiResponses({
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_DELETE_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_DELETE_FAILED),
                @ApiResponse(code = ErrCodeConstant.ERR_INVALID_INPUT_PARAM, message = ErrMsgConstant.MSG_INVALID_INPUT_PARAM),
        })
        public ResponseData delete(@RequestBody HashMap map) {
            String contentColumnIdsStr= (String) map.get("contentColumnIds");
            String[] contentColumnIdsTemp=contentColumnIdsStr.split(",");
            Long[] columnIds = (Long[]) ConvertUtils.convert(contentColumnIdsTemp,Long.class);
            return contentColumnService.deleteBatch(columnIds);
        }
    
        /**
         * 查询内容栏目列表
         * @return
         */
        @ApiOperation(value="查询内容栏目列表",httpMethod = "POST",notes = "返回内容栏目列表")
        @RequestMapping(value="/list",method = RequestMethod.POST)
        @ApiResponses({
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_SEARCH_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_SEARCH_FAILED),
        })
        public ResponseData contentColumnList(){
            return contentColumnService.queryAllContentColumn();
        }
    
        /**
         * 查询指定内容栏目信息
         * @param
         * @return
         */
        @ApiOperation(value = "查询指定内容栏目信息", httpMethod = "POST", notes = "返回内容栏目信息")
        @RequestMapping(value = "/info", method = RequestMethod.POST)
        @ApiImplicitParams({
                @ApiImplicitParam(name="uuid",value="内容栏目id",required=true,dataType = "Long",paramType = "path")
        })
        @ApiResponses({
                @ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_SEARCH_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_SEARCH_FAILED),
        })
        public ResponseData contentColumnInfoByColumnId(@RequestBody Map<String,Object> reqMap, HttpServletRequest request){
            Long contentColumnId=(Long) reqMap.get("uuid");
            return contentColumnService.queryContentColumnInfoByContentColumnId(contentColumnId);
        }
    
        private Long getUuid(HttpServletRequest request) {
            String token = request.getHeader("Authorization");
            String uuid = jwtTokenUtil.getUidFromToken(token);
            if (uuid == null)
                throw new CustomException(ErrCodeConstant.ERR_INVALID_TOKEN,ErrMsgConstant.MSG_INVALID_TOKEN);
            return Long.parseLong(jwtTokenUtil.getUidFromToken(token));
        }
    
    }

## 四、启动应用程序访问url ##

[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

## 五、返回结果 ##

![70 1][]

![70 2][]

## 六、API注解详情 ##

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

@RequestMappping此注解的推荐配置

value，method，produces

@ApiImplicitParam

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

说明：

*  @Api:用在类上，说明该类的作用
 *  @ApiOperation:用在方法上，说明方法的作用
 *  @ApiImplicitParams:用在方法上包含一组参数说明
 *  @ApiImplicitParam:用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

1.  paramType:参数放到哪个地方

header-->请求参数的获取：@RequestHeader

query-->请求参数的获取：@RequestParam

path（用于restful接口）-->请求参数的获取：@PathVariable

body（不常用）

form（不常用）

1.  name:参数名
2.  dataType:参数类型
3.  required:参数是否必须传入
4.  value:参数的意思
5.  defaultValue:参数的默认值

*  @ApiResponses:用于表示一组响应
 *  @ApiResponse:用在@ApiResponses中，一般用于表达一个错误的响应信息

1.  code:数字，例如400
2.  message：信息，例如“请求参数没填好!”
3.  response:抛出异常的类

*  @ApiModel:描述一个model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

1.  @ApiModelProperty:描述一个model的属性

以上这些就是最常用的注解了

[70]: /images/20220518/d741b75987bc45d68eca376d86f35479.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[70 1]: /images/20220518/0d5d6a77c8254ea48d80c8e99d92ef06.png
[70 2]: /images/20220518/f89de73e77e94124895e96c3207f691c.png