Springboot：Springboot+Swagger2集成服務

Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

Pom依賴

在pom.xml文件中添加swagger相關依賴

<!-- Swagger依賴包 -->
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
</dependency>
<!-- Swagger的ui界面 -->
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
</dependency>

配置Swagger 

新建Swagger配置類，需要特別注意的是Swagger scan base package,這是掃描注解的配置，即你的API接口位置，對前端提供服務接口的位置。

package com.example.demo.config;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API接口文檔")
                .description("用戶信息管理")
                .version("1.0.0")
                .build();
    }
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //這里寫的是API接口所在的包位置
 
                .paths(PathSelectors.any())
                .build();
    }
}

Swagger常用注解

- @Api()用於類； 

　　表示標識這個類是swagger的資源 
- @ApiOperation()用於方法； 

　　表示一個http請求的操作 
- @ApiParam()用於方法，參數，字段說明； 

　　表示對參數的添加元數據（說明或是否必填等） 
- @ApiModel()用於類 

　　表示對類進行說明，用於參數用實體類接收 
- @ApiModelProperty()用於方法，字段 

　　表示對model屬性的說明或者數據操作更改 
- @ApiIgnore()用於類，方法，方法參數 

　　表示這個方法或者類被忽略 
- @ApiImplicitParam() 用於方法 

　　表示單獨的請求參數 
- @ApiImplicitParams() 用於方法，

　　包含多個 @ApiImplicitParam

 使用舉例說明

 @Api() 
用於類；表示標識這個類是swagger的資源 
tags–表示說明 
value–也是說明，可以使用tags替代 
但是tags如果有多個值，會生成多個list

@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController { }

 

 

 

 @ApiOperation() 

用於方法；表示一個http請求的操作 
value用於方法描述 
notes用於提示內容 
tags可以重新分組（視情況而用） 
@ApiParam() 

用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等） 
name–參數名 
value–參數說明 
required–是否必填

@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController { 

    @ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點") 
    @GetMapping("/getUserInfo")
    public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) { 
        // userService可忽略，是業務邏輯 
        User user = userService.getUserInfo(); 
        return user; 
    } 
}

 @ApiModel()

用於類 ；表示對類進行說明，用於參數用實體類接收 

value–表示對象名 
description–描述 
都可省略 
@ApiModelProperty()

用於方法，字段； 表示對model屬性的說明或者數據操作更改 
value–字段說明 
name–重寫屬性名字 
dataType–重寫屬性類型 
required–是否必填 
example–舉例說明 
hidden–隱藏

@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{ 
    private static final long serialVersionUID = 1L; 
    @ApiModelProperty(value="用戶名",name="username",example="xingguo") 
    private String username; 
    @ApiModelProperty(value="狀態",name="state",required=true) 
    private Integer state; 
    private String password; 
    private String nickName; 
    private Integer isDeleted; 
    @ApiModelProperty(value="id數組",hidden=true) 
    private String[] ids; 
    private List<String> idList; 
    //省略get/set 
}

@ApiOperation("更改用戶信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){ 
    int num = userService.updateUserInfo(user); 
    return num; 
}

 

 

@ApiIgnore()

用於類或者方法上，可以不被swagger顯示在頁面上 
比較簡單, 這里不做舉例

@ApiImplicitParam() 

用於方法 
表示單獨的請求參數 
@ApiImplicitParams() 

用於方法，包含多個 @ApiImplicitParam 
name–參數ming 
value–參數說明 
dataType–數據類型 
paramType–參數類型 
example–舉例說明

@ApiOperation("查詢測試")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query") 
@ApiImplicitParams({ @ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"), @ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")}) 
public void select(){ }

 文章轉載至：https://blog.csdn.net/wyb880501/article/details/79576784