springboot 集成swagger2

使用Swagger 可以動態生成Api接口文檔，在項目開發過程中可以幫助前端開發同事減少和后端同事的溝通成本，而是直接參照生成的API接口文檔進行開發，提高了開發效率。這里以springboot(版本2.1.4.RELEASE)集成swagger2並以簡單測試用例延時集成效果。

1、准備工作

pom依賴加入swagger

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置文件application.properties可以添加swagger.enabled配置控制是否開啟

# 控制開啟或關閉swagger
swagger.enabled=true

添加swagger配置類，主要用於配置生成api的相關信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    /**
     * 控制開啟或關閉swagger
     */
    @Value("${swagger.enabled}")
    private boolean swaggerEnabled;
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // api基礎信息
                .apiInfo(apiInfo())
                // 控制開啟或關閉swagger
                .enable(swaggerEnabled)
                // 選擇那些路徑和api會生成document
                .select()
                // 掃描展示api的路徑包
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                // 對所有路徑進行監控
                .paths(PathSelectors.any())
                // 構建
                .build();
    }

    /**
     * @descripiton:
     * @author: kinson
     * @date: 2019/9/10 23:33
     * @param
     * @exception：
     * @modifier：
     * @return：springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // api名稱
                .title("SwaggerUI APIS")
                // api 描述
                .description("Simple Demo About SwaggerUI APIS")
                // api 版本
                .version("1.0")
                // 構建
                .build();
    }
}

這里的@EnableSwagger2用於讓激活swagger，也可以加載啟動類上。

添加測試url

@RestController
@Api(tags = "測試demo")
@RequestMapping(value = "swagger")
public class SwaggerController {

    @ApiOperation(value = "hello", notes = "hello測試api")
    @GetMapping(value = "hello")
    public String hello() {
        return "hello";
    }

    @ApiOperation(value = "add", notes = "路徑變量測試")
    @ApiImplicitParam(name = "swaggerId",value = "測試參數id",required = true, dataType = "Integer", paramType="path")
    @PostMapping(value = "add/{swaggerId}")
    public String add(@PathVariable Integer swaggerId) {
        Assert.notNull(swaggerId, "swaggerId為空");
        return swaggerId.toString();
    }

    @ApiOperation(value = "update",notes = "多路徑參數變量測試")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "swaggerId",value = "測試參數id",required = true, dataType = "Integer", paramType="path"),
            @ApiImplicitParam(name = "name",value = "測試參數名稱",required = true, dataType = "String", paramType="path")})
    @PutMapping(value = "/update/{swaggerId}/{name}")
    public String update(@PathVariable Integer swaggerId,@PathVariable String name) {
        return String.valueOf(swaggerId + name);
    }

    @ApiOperation(value = "addUser",notes = "對象添加測試")
    @ApiImplicitParam(name = "user",value = "待添加用戶信息",required = true, dataType = "User", paramType="body")
    @ApiResponse(code = 200, message = "添加成功")
    @PostMapping(value = "/addUser")
    public String addUser(@RequestBody User user){

        return user.getName();
    }

}

上述工作加完后就可以啟動項目查看效果，打開瀏覽器訪問http://127.0.0.1:8080/swagger-ui.html，如下圖則表示集成成功

 2、swagger 相關注解

• @Api：用在類上，標志此類是Swagger資源 value：接口說明 tags：接口說明，可以在頁面中顯示。可以配置多個，當配置多個的時候，在頁面中會顯示多個接口的信息
• @ApiOperation：用在方法上，描述方法的作用
• @ApiImplicitParams：包裝器，包含多個ApiImplicitParam對象列表
• @ApiImplicitParam：定義在@ApiImplicitParams注解中，定義單個參數詳細信息，如下：　　

　　　　○ paramType：參數放在哪個地方
　　　　　　§ header-->請求參數的獲取：@RequestHeader
　　　　　　§ query-->請求參數的獲取：@RequestParam
　　　　　　§ path（用於restful接口）-->請求參數的獲取：@PathVariable
　　　　　　§ body（以流的形式提交 僅支持POST）
　　　　　　§ form（以form表單的形式提交 僅支持POST）
　　　　○ name：參數名
　　　　○ dataType：參數的數據類型 只作為標志說明，並沒有實際驗證
　　　　　　§ Long
　　　　　　§ String
　　　　○ required：參數是否必須傳
　　　　　　§ true
　　　　　　§ false
　　　　○ value：參數的意義
　　　　○ defaultValue：參數的默認值

• @ApiModel：描述一個Swagger Model的額外信息
• @ApiModel用在類上，表示對類進行說明，用於實體類中的參數接收說明
• @ApiModelProperty：在model類的屬性添加屬性說明
• @ApiParam：用於Controller中方法的參數說明
• @ApiResponses：包裝器：包含多個ApiResponse對象列表
• @ApiResponse：定義在@ApiResponses注解中，一般用於描述一個錯誤的響應信息 。如下：
  • code：錯誤碼，例如400
  • message：信息，例如"請求參數沒填好"
  • response：拋出異常的類
• @Authorization 聲明要在資源或操作上使用的授權方案。
• @AuthorizationScope 描述OAuth2授權范圍

 

Github源碼參照