SpringBoot + SwaggerUI

時間 2019-12-10

標籤 springboot swaggerui 欄目 Spring 简体版

原文原文鏈接

後臺寫接口，因爲要提供接口文檔給前臺使用，全部研究了一下swagger,看到網上有篇文章寫得不錯，就直接拿過來了。html

swagger用於定義API文檔。java

好處：git

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

一、項目結構github

和上一節同樣，沒有改變。web

二、pom.xmlspring

引入了兩個jar。後端

 
         <dependency> 
        
         <groupId>io.springfox</groupId> 
        
         <artifactId>springfox-swagger2</artifactId> 
        
         <version> 
         2.2 
         . 
         2 
         </version> 
        
         </dependency> 
        
         <dependency> 
        
         <groupId>io.springfox</groupId> 
        
         <artifactId>springfox-swagger-ui</artifactId> 
        
         <version> 
         2.2 
         . 
         2 
         </version> 
        
         </dependency>

三、Application.java api

 
         package 
         com.xxx.firstboot; 
        
         import 
         org.springframework.boot.SpringApplication; 
        
         import 
         org.springframework.boot.autoconfigure.SpringBootApplication; 
        
         import 
         springfox.documentation.swagger2.annotations.EnableSwagger2; 
        
         @SpringBootApplication        
         //same as @Configuration+@EnableAutoConfiguration+@ComponentScan 
        
         @EnableSwagger2             
         //啓動swagger註解 
        
         public 
         class 
         Application { 
        
         public 
         static 
         void 
         main(String[] args) { 
        
         SpringApplication.run(Application. 
         class 
         , args); 
        
         } 
        
         }

說明：瀏覽器

引入了一個註解@EnableSwagger2四、UserController.javarestful

 
         package 
         com.xxx.firstboot.web; 
        
         import 
         org.springframework.beans.factory.annotation.Autowired; 
        
         import 
         org.springframework.web.bind.annotation.RequestHeader; 
        
         import 
         org.springframework.web.bind.annotation.RequestMapping; 
        
         import 
         org.springframework.web.bind.annotation.RequestMethod; 
        
         import 
         org.springframework.web.bind.annotation.RequestParam; 
        
         import 
         org.springframework.web.bind.annotation.RestController; 
        
         import 
         com.xxx.firstboot.domain.User; 
        
         import 
         com.xxx.firstboot.service.UserService; 
        
         import 
         io.swagger.annotations.Api; 
        
         import 
         io.swagger.annotations.ApiImplicitParam; 
        
         import 
         io.swagger.annotations.ApiImplicitParams; 
        
         import 
         io.swagger.annotations.ApiOperation; 
        
         import 
         io.swagger.annotations.ApiResponse; 
        
         import 
         io.swagger.annotations.ApiResponses; 
        
         @RestController 
        
         @RequestMapping 
         ( 
         "/user" 
         ) 
        
         @Api 
         ( 
         "userController相關api" 
         ) 
        
         public 
         class 
         UserController { 
        
         @Autowired 
        
         private 
         UserService userService; 
        
         //    @Autowired 
        
         //    private MyRedisTemplate myRedisTemplate; 
        
         @ApiOperation 
         ( 
         "獲取用戶信息" 
         ) 
        
         @ApiImplicitParams 
         ({ 
        
         @ApiImplicitParam 
         (paramType= 
         "header" 
         ,name= 
         "username" 
         ,dataType= 
         "String" 
         ,required= 
         true 
         ,value= 
         "用戶的姓名" 
         ,defaultValue= 
         "zhaojigang" 
         ), 
        
         @ApiImplicitParam 
         (paramType= 
         "query" 
         ,name= 
         "password" 
         ,dataType= 
         "String" 
         ,required= 
         true 
         ,value= 
         "用戶的密碼" 
         ,defaultValue= 
         "wangna" 
         ) 
        
         }) 
        
         @ApiResponses 
         ({ 
        
         @ApiResponse 
         (code= 
         400 
         ,message= 
         "請求參數沒填好" 
         ), 
        
         @ApiResponse 
         (code= 
         404 
         ,message= 
         "請求路徑沒有或頁面跳轉路徑不對" 
         ) 
        
         }) 
        
         @RequestMapping 
         (value= 
         "/getUser" 
         ,method=RequestMethod.GET) 
        
         public 
         User getUser( 
         @RequestHeader 
         ( 
         "username" 
         ) String username,  
         @RequestParam 
         ( 
         "password" 
         ) String password) { 
        
         return 
         userService.getUser(username,password); 
        
         } 
        
         //    @RequestMapping("/testJedisCluster") 
        
         //    public User testJedisCluster(@RequestParam("username") String username){ 
        
         //        String value =  myRedisTemplate.get(MyConstants.USER_FORWARD_CACHE_PREFIX, username); 
        
         //        if(StringUtils.isBlank(value)){ 
        
         //            myRedisTemplate.set(MyConstants.USER_FORWARD_CACHE_PREFIX, username, JSON.toJSONString(getUser())); 
        
         //            return null; 
        
         //        } 
        
         //        return JSON.parseObject(value, User.class); 
        
         //    } 
        
         }

說明：

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