Swagger(二)簡單使用

     在項目開發中，我們經常需要進行前後端接口聯調的工作，以往通過api接口文檔進行接口的描述，一旦接口有什麼改動，就需要進行api文檔的更改，很不友善，現在我們可以通過swagger進行接口的線上檢視和調用，非常友善，如果你對swagger不是很了解，請看這裡：5分鐘了解swagger 。

     下面以springboot為例，進行swagger的配置使用說明，具體如下：

1、引入pom 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
           

2、swagger配置 

/**
 * @ClassName: SwaggerConfig  
 * @Description: swagger配置
 * @author ejshi  
 * @date 2018年1月31日 下午7:53:38  
 */
@SpringBootConfiguration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.regulus.account.consumer.controller"))
                .paths(PathSelectors.any())
//                .paths(Predicates.or(PathSelectors.regex("/[api|demo]/.*")))//過濾的接口
                .build();
    }
 
    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .description("Api Documentation")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(new Contact("shijun", "https://swagger.io/", "[email protected]"))
                .build();
    }
}
           

3、controller接口類中使用swagger   

@Api(value= "UserController",tags ="使用者管理" ,description="使用者管理相關功能API")
@RestController
public class UserController {
    
    @Reference
    private UserProvider userProvider;
    
    @ApiOperation(value = "新增" ,notes="新增資料記錄")
    @PostMapping(path = "/user/add")
    public ResponseJson<Object> addUser(
            @ApiParam("請求參數") @RequestBody @Validated(UserRequest.Add.class) UserRequest  userRequest){
        
        User user = BeanCopierUtil.invoke(userRequest, User.class);
        user.setId(StringUtil.uuid());
        
        userProvider.insertSelective(user);
        
        return new ResponseJson<Object>(true, ResponseCodeEnum.SUCCESS);
    }
    
    @ApiOperation(value = "查詢" ,notes="查詢相應資料記錄，分頁顯示")
    @GetMapping(path = "/user/listPage")
    public ResponseJson<List<UserResponse>> listPageUser(@ApiParam("請求資料") UserQuery userQuery){
        User user = BeanCopierUtil.invoke(userQuery, User.class);
        
        PageResultModel<User> pageResult = userProvider.selectWithPage(user, userQuery.getPageNum(), userQuery.getPageSize());
        
        List<UserResponse> userResponses = BeanCopierUtil.invokeList(pageResult.getDataList(), UserResponse.class);
        
        return new ResponseJson<List<UserResponse>>(true, ResponseCodeEnum.SUCCESS, userResponses,pageResult.getTotal());
    }
}
           

 4、請求參數類，如UserQuery中使用swagger注解 

@ApiModel
public class UserQuery {
    private static final long serialVersionUID = -2840366087876556526L;
 
    @ApiModelProperty("使用者名")
    private String username;
        
    @ApiModelProperty("使用者狀态")
        private String userStatus;
    
    //省略get/set方法
 
}
           

   5、swagger線上api如圖所示

   6、簡單swagger注解參數講解 

注解    常見用法
@Api    用于controller類上
@ApiOperation    用于controller中的接口方法上
@ApiParam    用于請求參數
@ApiModel    用于請求或者響應類上，如UserQuery 
@ApiModelProperty    用于@ApiModel注解類中的屬性上