swagger2的基本使用

這里主要講解在spring boot中使用swagger2 生成接口文檔

首先導入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>

 

然后新建一個配置類 用於配置一些swagger2的文檔基本信息和接口掃描路徑

/**
 * Swagger2 配置類
 * 在與spring boot 集成時，放在與application.java 同級的目錄下
 * 通過@Configuration注解，讓spring來加載該配置
 */
@Configuration
public class Swagger2 {


    /**
     * 創建API應用
     * appinfo()增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例，用來控制那些接口暴露給Swagger來展現
     * 本例采用置頂掃描的包路徑來定義指定要建立API的目錄
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.shuke.chat"))
                .paths(PathSelectors.any()).build();
        return docket;
    }


    /**
     * 創建改API的基本信息（這些基本信息會展示在文檔頁面中）
     * 訪問地址： http://項目實際地址/swagger-ui.html
     * @return
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()

                 // 設置頁面標題 .title("使用swagger2構建小程序后端api接口文檔") // 設置聯系人 .contact(new Contact("IT人故事會", "http://idig8.com", "公眾號：編程坑太多")) // 描述 .description("歡迎訪問接口文檔") // 定義版本號 .version("1.0").build();

 } }

 

然后在啟動類上 加@EableSwagger2 

默認swagger2的界面地址是:項目的根路徑/swagger-ui.html

進入這個界面以后就會顯示當前項目有哪些接口  點擊接口以后就會顯示當前接口有哪些方法  還可以在線測試 功能非常強大 可以替代postman了

具體操作非常簡單 看到了就會

 

接下來將swagger2的核心 就是使用注解給接口 和每個方法加說明

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該注解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams：多個請求參數