Swagger 2.0 整合配置

x號開發者發表於2019-04-10
Swagger

傳統的API文件編寫存在以下幾個痛點：

對API文件進行更新的時候，需要通知前端開發人員，導致文件更新交流不及時；

API介面返回資訊不明確

 

大公司中肯定會有專門文件伺服器對介面文件進行更新。

 

 

缺乏線上介面測試，通常需要使用相應的API測試工具，比如postman、SoapUI等

介面文件太多，不便於管理

為了解決傳統API介面文件維護的問題，為了方便進行測試後臺Restful介面並實現動態的更新，因而引入Swagger介面工具。

 

Swagger具有以下優點

1.功能豐富：支援多種註解，自動生成介面文件介面，支援在介面測試API介面功能；

2.及時更新：開發過程中花一點寫註釋的時間，就可以及時的更新API文件，省心省力；

3.整合簡單：通過新增pom依賴和簡單配置，內嵌於應用中就可同時釋出API介面文件介面，不需要部署獨立服務。

 

springboot整合

Maven依賴資訊

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.RELEASE</version>
    </parent>
    <!-- 管理依賴 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Finchley.M7</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <!-- SpringBoot整合Web元件 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- SpringBoot整合eureka客戶端 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <!-- swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
    </dependencies>
    <!-- 注意： 這裡必須要新增， 否者各種依賴有問題 -->
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/libs-milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // api掃包
                .apis(RequestHandlerSelectors.basePackage("com.itmayiedu.api")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("電商系統").description("Java分散式")
                .termsOfServiceUrl("http://www")
                // .contact(contact)
                .version("1.0").build();
    }

}

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

 

Zull整合Swagger管理微服務所有API

會員和訂單引入Maven依賴

        <!-- swagger-spring-boot -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

application.yml配置

Api介面掃描範圍

swagger:
  base-package: com.itmayeidu.api

ZuulGateway閘道器

@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class AppGateWay {

    // @EnableZuulProxy 開啟閘道器代理

    public static void main(String[] args) {
        SpringApplication.run(AppGateWay.class, args);
    }

    // zuul配置能夠使用config實現實時更新
    @RefreshScope
    @ConfigurationProperties("zuul")
    public ZuulProperties zuulProperties() {
        return new ZuulProperties();
    }

    // 新增文件來源
    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            // app-itmayiedu-order
            resources.add(swaggerResource("app-itmayiedu-member", "/api-member/v2/api-docs", "2.0"));
            resources.add(swaggerResource("app-itmayiedu-order", "/api-order/v2/api-docs", "2.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;
        }
    }

}

Maven依賴資訊

        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

 

相關文章