Swagger註解

swagger註解說明

 　　 一、與模型相關的註解,用在bean上面

　　　　@ApiModel：用在bean上，對模型類作註釋；

　　　　@ApiModelProperty：用在屬性上，對屬性作註釋

　　二、與接口相關的註解

　　　　@Api：用在controller上，對controller進行註釋；

　　　　@ApiOperation：用在API方法上，對該API作註釋，說明API的做用；

　　　　@ApiImplicitParams：用來包含API的一組參數註解，能夠簡單的理解爲參數註解的集合聲明； 

　　　　@ApiImplicitParam：用在@ApiImplicitParams註解中，也能夠單獨使用，說明一個請求參數的各個方面，該註解包含的經常使用選項有：

　　　　　　paramType：參數所放置的地方，包含query、header、path、body以及form，最經常使用的是前四個。

　　　　　　name：參數名；

　　　　　　dataType：參數類型，能夠是基礎數據類型，也能夠是一個class；

　　　　　　required：參數是否必須傳；

　　　　　　value：參數的註釋，說明參數的意義；

　　　　　　defaultValue：參數的默認值；

　　　　

　　　 @ApiResponses：一般用來包含接口的一組響應註解，能夠簡單的理解爲響應註解的集合聲明；

　　　 @ApiResponse：用在@ApiResponses中，通常用於表達一個響應信息

　　　　　　code：即httpCode，例如400 

　　　　　　message：信息，例如"操做成功"

　　　　　　response = UserVo.class  這裏UserVo是一個配置了@ApiModel註解的對像，該是對像屬性已配置 @ApiModelProperty,swagger能夠經過這些配置，生　成接口返回值

 

代碼例子:

    @ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")     @ApiImplicitParam(paramType="path", name = "id", value = "用戶ID", required = true, dataType = "Long")     @RequestMapping(value="/{id}", method=RequestMethod.GET)     public User getUser(@PathVariable Long id) {         return users.get(id);     } 

 

網上好多例子都沒有paramType這個參數，致使獲取不到URL的參數，特地記錄一下

詳細的註解說明

• @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的屬性

1 2 3 4 5 6 7 8 9 10 11 12 13 14

@ApiOperation (value= "添加博客" , notes= "新增博客" )      @ApiImplicitParams ({              @ApiImplicitParam (name =  "mess" , value =  "博客內容" ,                      required =  true , paramType =  "query" , dataType =  "String" )      })      @RequestMapping (value =  "/addblog" , method = RequestMethod.POST)      public  Result addBlog( @RequestBody  Blog blog,  @RequestParam (name =  "mess" , required =  true )String mess, HttpServletRequest request){          Integer userId = (Integer) request.getSession().getAttribute( "userId" );          userId =  12 ;          Integer effecNum = blogService.addBlog(blog, mess, userId);          if (effecNum >  0 )              return  new  Result(ResultEnums.SUCCESS);          return  new  Result(ResultEnums.PARAM_IS_INVAILD);      }