springboot整合swagger教程

1.swagger介紹

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

Swagger的作用：

1，接口的文檔在線自動生成。

2，功能測試。

 

2.接入步驟

 

   2.1 在maven中添加依賴

<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>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.4</version>
</dependency>

 

2.2 創建swagger的配置類

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author zj
 * @date 2019-11-28
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())//添加說明
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XX.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
                .title("XXXX接口文檔")
                .description("XXXX接口文檔")
                .version("1.0")
                .build();
    }  
}

  2.3 swagger常用註解使用說明

 

1.@Api:用在類上，說明該類的作用。

2. @ApiOperation:註解來給API增加方法說明。

3.@ApiImplicitParams:用在方法上包含一組參數說明。

  @ApiImplicitParam：用來註解來給方法入參增加說明。

5.@ApiResponses: 用於表示一組響應。

@ApiResponse: 用在@ApiResponses中，一般用於表達一個錯誤的響應信息。

code：數字，例如400

• • message：信息，例如"請求參數沒填好"
  • response：拋出異常的類

 

7.@ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam註解進行描述的時候）

 2.4 接口文檔頁面的訪問方式

 

1.springfox-swagger-ui

項目ip:端口/swagger-ui.html    示例：localhost:8080/swagger-ui.html

 

 

2.swagger-bootstrap-ui

項目ip:端口/doc.html    示例：localhost:8080/doc.html