SpringBoot整合Swagger2的示例分析

小編給大家分享一下SpringBoot整合Swagger2的示例分析，相信大部分人都還不怎么了解，因此分享這篇文章給大家參考一下，希望大家閱讀完這篇文章后大有收獲，下面讓我們一起去了解一下吧！

前言

springBoot作為微服務首選框架，為其他服務提供大量的接口服務。接口對接方需要實時最近的接口文檔。

swagger可以通過代碼和注釋自動為web項目生成在線文檔，這里使用swagger。

當 SpringBoot 代碼中 SpringMVC 使用自動化配置類 WebMvcAutoConfiguration 時，其整合 Swagger2 的方法如下。

如果 SpringMVC 的配置過程使用了 WebMvcConfigurationSupport；則如下的整合方法不適合。

一、Spring Boot Web 整合 Swagger2 過程

Spring Boot Web 項目整合 Swagger2 主要有兩個過程：

1. 添加 Swagger2 相關依賴。

2. 配置 Swagger2 配置類。
   

1.1、添加 Swagger2 相關依賴

首先要對 Spring Boot Web 的項目，添加 Swagger2 相關的依賴：

<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <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>

1.2、配置 Swagger2 配置類

@Configuration
@EnableSwagger2
public class Swagger {
   //創建 Docket 的Bean
   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         //select() 函數返回一個 ApiSelectorBuilder實例用來控制哪些接口暴露給 Swagger 來展現
         .select()
         //要掃描的包
         .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
  //選擇API路徑
         .paths(PathSelectors.any())
         .build();
   }
  //創建文檔的基本信息
   public ApiInfo apiInfo(){
       return new ApiInfoBuilder()
         .title("Swagger UI 的標題")
         .description("用restful風格寫接口")
         .termsOfServiceUrl("")
         .version("1.0")
         .build();
   }
}

二、配置 Swagger2 接口常用注解

2.1、@Api 請求類說明

寫在controller類定義上方,用于說明類的作用。

@Api(value = "Swagger Test Control", 
     description = "演示Swagger用法的Control類", 
     tags = "Swagger Test Control Tag")

2.2、@ApiOperation 方法的說明

寫在REST接口上方，用于說明方法的作用。

@ApiOperation(
value="創建用戶", 
notes="根據User對象創建用戶")

2.3、@ApiImplicitParams 和 @ApiImplicitParam 方法參數說明

@ApiImplicitParams：用在請求的方法上，包含一組參數說明
    @ApiImplicitParam：對單個參數的說明      
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用于restful接口）--> 請求參數的獲取：@PathVariable
            · body（請求體）-->  @RequestBody User user
            · form（普通表單提交）     
        dataType：參數類型，默認String，其它值dataType="int"       
        defaultValue：參數的默認值
--------------------------------------------------------------------
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "ID", dataType = "Long"),
    @ApiImplicitParam(name = "user", value = "用戶", dataType = "User")
})

2.4、@ApiResponses 和 @ApiResponse 方法返回值的說明

@ApiResponses：方法返回對象的說明
    @ApiResponse：每個參數的說明
        code：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類
-------------------------------------------------------------------
@ApiResponses({
    @ApiResponse(code = 400, message = "權限不足"),
    @ApiResponse(code = 500, message = "服務器內部異常") }
)

2.5、@ApiModel 和 @ApiModelProperty

@ApiModel 用于JavaBean 上面，表示一個JavaBean。這種一般用在post創建的時候，使用 @RequestBody 這樣的場景，請求參數無法使用 @ApiImplicitParam 注解進行描述的時候。

@ApiModelProperty 用對象接收參數時，描述對象的一個字段。

@ApiModel( description = "學生")
public class Student {
    @ApiModelProperty(value = "主鍵id")
    private String id;
    @ApiModelProperty(value = "名稱", required = true)
    private String name;
    @ApiModelProperty(value = "年齡", required = true)
    private int age;
}

2.6、其他注解

@ApiIgnore ：使用該注解忽略這個API，不對這個接口生成文檔。

@ApiError：發生錯誤返回的信息

以上是“SpringBoot整合Swagger2的示例分析”這篇文章的所有內容，感謝各位的閱讀！相信大家都有了一定的了解，希望分享的內容對大家有所幫助，如果還想學習更多知識，歡迎關注億速云行業資訊頻道！