【Spring Boot】2.Swagger API

一、Swagger介紹

swagger用於定義API文檔，返回數據格式是json，用的是restful風格。

優點：

前後端分離開發
API文檔非常明確
測試的時候不需要再使用URL輸入瀏覽器的方式來訪問Controller
傳統的輸入URL的測試方式對於post請求的傳參比較麻煩（當然，可以使用postman這樣的瀏覽器插件）
spring boot與swagger的集成簡單

spring boot中使用swagger2構建RESTful APIs

二、技術與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

五、返回結果

六、API註解詳情

作用範圍	API	使用位置
對象屬性	@ApiModelProperty	用在出入參數對象的字段上
協議集描述	@Api	用於Controller類上
協議描述	@ApiOperation	用在Controller的方法上
Response集	@ApiResponses	用在Controller的方法上
Response	@ApiResponse	用在@ApiResponses裏面
非對象參數集	@ApiImplicitParams	用在Controller的方法上
非對象參數描述	@ApiImplicitParam	用在@ApiImplicitParams的方法裏面
描述返回對象的意義	@ApiModel	用在返回對象的類上

@RequestMappping此註解的推薦配置

value，method，produces

@ApiImplicitParam

屬性	取值	作用
paramType		查詢參數類型
	path	以地址的形式提交數據
	query	直接跟參數完成自動映射賦值
	body	以流的形式提交僅支持POST
	header	參數在request headers裏邊提交
	form	以form表單的形式提交僅支持POST
dataType		參數的數據類型只作爲標誌說明並沒有實際驗證
	Long
	String
name		接收參數名
value		接收參數的意義描述
required		參數是否必填
	true	必填
	false	非必填
defaultValue		默認值

說明：

@Api:用在類上，說明該類的作用
@ApiOperation:用在方法上，說明方法的作用
@ApiImplicitParams:用在方法上包含一組參數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中，指定一個請求參數的各個方面

paramType:參數放到哪個地方

header-->請求參數的獲取：@RequestHeader

query-->請求參數的獲取：@RequestParam

path（用於restful接口）-->請求參數的獲取：@PathVariable

body（不常用）

form（不常用）

name:參數名
dataType:參數類型
required:參數是否必須傳入
value:參數的意思
defaultValue:參數的默認值

@ApiResponses:用於表示一組響應
@ApiResponse:用在@ApiResponses中，一般用於表達一個錯誤的響應信息

code:數字，例如400
message：信息，例如“請求參數沒填好!”
response:拋出異常的類

@ApiModel:描述一個model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）

@ApiModelProperty:描述一個model的屬性

以上這些就是最常用的註解了

【Spring Boot】2.Swagger API

一、Swagger介紹

二、技術與IDE

三、具體應用

四、啓動應用程序訪問url

五、返回結果

六、API註解詳情

【微信_小程序】3.小程序IOS web-view內嵌二維碼頁面長按出現兩個保存提示框

【Vue】22.vue組件級路由鉤子函數(beforeRouteEnter/beforeRouteUpdate/beforeRouteLeave)

【微信_小程序】2.微信小程序web-view內嵌公衆號網頁

【Vue】20.vue項目中引入echarts圖表遇到的問題

【web前端】15.input輸入框的一些問題

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結