swagger的使用

傳統文檔的痛點

• 對API文檔進行更新的時候，須要通知前端開發人員，致使文檔更新交流不及時；

• API接口返回信息不明確

• 大公司中確定會有專門文檔服務器對接口文檔進行更新。

• 缺少在線接口測試，一般須要使用相應的API測試工具，好比postman、SoapUI等

• 接口文檔太多，不便於管理

Swagger具備如下優勢

• 功能豐富：支持多種註解，自動生成接口文檔界面，支持在界面測試API接口功能；

• 及時更新：開發過程當中花一點寫註釋的時間，就能夠及時的更新API文檔，省心省力；

• 整合簡單：經過添加 pom 依賴和簡單配置，內嵌於應用中就可同時發佈API接口文檔界面，不須要部署獨立服務。

使用springboot的集成

後面會又springCloud的和zuul整合進行文檔的管理

依賴文件

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.RELEASE</version>
    </parent>

    <dependencies>
        <!-- SpringBoot整合Web組件 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--SpringBoot swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <!--SpringBoot swagger2 -UI -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
    </dependencies>

文件的配置類（java形式的）

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 自行修改成本身的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.king.swagerr.controller")).paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("api文檔").description("restfun 風格接口")
                // 服務條款網址
                // .termsOfServiceUrl("http://blog.csdn.net/forezp")
                .version("1.0")
                // .contact(new Contact("帥呆了", "url", "email"))
                .build();
    }
}

接口類

@RestController
@RequestMapping("api")
@Api("swaggerDemoController相關的api")
public class SwaggerDemoController {

    private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);

    @ApiOperation(value = "根據id查詢學生信息", notes = "查詢數據庫中某個的學生信息")
    @ApiImplicitParam(name = "id", value = "學生ID", paramType = "path", required = true, dataType = "Integer")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)  // 必須聲明請求方法，負責會生成好多個無用說明
    public String getStudent(@PathVariable int id) {
        logger.info("開始查詢某個學生信息");
        return "success";
    }

}

訪問地址 http://localhost:8080//swagger-ui.html#/

zuul網關整合Swagger

zuulServer 網關的配置，其餘的配置忽略了

zuul:
  routes:
    api-a:
      path: /api-member/**
      service-id: service-member
    api-b:
      path: /api-order/**
      service-id: service-order

依賴文件,統一都用這一個

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

zuulServer的Swagger的配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("分佈式購物系統")
                .description("購物系統接口文檔說明")
                .termsOfServiceUrl("http://localhost:8081")
                .contact(new Contact("guoning", "", "1260408088@qq.com"))
                .version("1.0")
                .build();
    }
}

orderServer與userServer配置相同：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.order.controller")) // 掃描包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() { // 下面的信息，自行更改
        return new ApiInfoBuilder()
                .title("購物系統-訂單模塊")
                .description("購物系統訂單模塊接口文檔說明")
                .termsOfServiceUrl("http://localhost:8083")
                .contact(new Contact("guoning", "", "1260408088@qq.com"))
                .version("1.0")
                .build();
    }
}

controller中的配置,

@RestController
@RequestMapping("api")
@Api("swaggerDemoController相關的api")
public class SwaggerDemoController {
    
    private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);

    @ApiOperation(value = "根據id查詢學生信息", notes = "查詢數據庫中某個的學生信息") // 描述
    @ApiImplicitParam(name = "id", value = "學生ID", paramType = "path",required = true, dataType = "Integer") // 參數描述
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)  // 必須聲明請求方法，負責會生成好多個無用說明
    public String getStudent(@PathVariable int id) {
        logger.info("開始查詢某個學生信息");
        return "success";
    }

}

就到這了，其中有參考了 https://www.jianshu.com/p/af4ff19afa04 ，由於課程視頻中不太詳細。