一、關於Swagger

Swagger能成為最受歡迎的REST APIs文件生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制檯，開發者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK程式碼用於各種不同的平臺上的實現。
• Swagger 檔案可以在許多不同的平臺上從程式碼註釋中自動生成。
• Swagger 有一個強大的社群，裡面有許多強悍的貢獻者

二、該篇部落格使用技術版本

springcloud：Dalston.SR5

springboot：1.5.9.RELEASE

springfox-swagger-ui：2.7.0

pringfox-swagger2：2.7.0

zuul-core：1.3.0

三、開發實現

1、在總依賴中新增swagger相關依賴(因為多處地方會使用)

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

2、在閘道器服務下建立swagger

首先閘道器路由先配置好，如下

zuul:
  host:
    connect-timeout-millis: 3000
    socket-timeout-millis: 3000
  #路由規則
  routes:
    api-user:
      path: /api/user/**
      serviceId: wc-client-user
      #防止閘道器轉發請求後session失效
      sensitiveHeaders: "*"
    api-search:
      path: /api/search/**
      serviceId: wc-client-search
      sensitiveHeaders: "*"
 

這裡主要建立DocumentationConfig和SwaggerConfig，目錄如下

DocumentationConfig.java

/**
 * 資源文件配置類
 */
@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider{

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("搜尋服務介面", "/api/search/v2/api-docs", "1.0"));// /api/search/是閘道器路由，/v2/api-docs是swagger中的
        resources.add(swaggerResource("使用者服務介面", "/api/user/v2/api-docs", "1.0"));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }

}

SwaggerConfig.java

/**
 * 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("WingCloud")
                .description("WingCloud")
                .termsOfServiceUrl("http://localhost:8080")//閘道器埠
                .version("1.0")
                .build();
    }

    @Bean
    UiConfiguration uiConfig() {
        return new UiConfiguration(null, "list", "alpha", "schema",
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
    }

}

3、在閘道器啟動類上加上@EnableSwagger2註解

4、在client服務內的controller中進行註明

筆者這裡以user服務為例

如下在類上新增@Api，在方法上新增@ApiOperation，當然還有其他註解，讀者可自行百度/谷歌

/**
 * 使用者請求處理控制器
 */
@Api("使用者管理介面")
@RestController
public class UserController extends BaseController {

    @Autowired
    private IUserService userService;

    /**
     * 使用者登入
     * @param request
     * @param result
     * @param req
     * @return
     */
    @ApiOperation(value = "/login",notes = "登入介面")
    @RequestMapping("/login")
    public SingleResult<TokenResponse> login(@Valid @RequestBody LoginRequest request, BindingResult result,HttpServletRequest req){
        //必須要呼叫validate方法才能實現輸入引數的合法性校驗
        System.out.println("-------------test-----------");
        validate(result);
        return userService.login(request,req);
    }
}

5、在client服務中新增Swagger配置

如下圖目錄

SwaggerConfig.java

/**
 * swagger配置
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("top.wingcloud.controller"))//過濾的路徑
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("wc-client-user")
                .description("介面文件說明")
                .contact(new Contact("淺然", "", "[email protected]"))
                .version("2.0")
                .build();
    }
}

ok，配置整合完成後，啟動相應的服務，然後進入http://localhost:8080/swagger-ui.html即可看到如下介面