Swagger自动生成API文档

Swagger具有以下优点

1. 功能丰富：支持多种注解，自动生成接口文档界面。支持在界面测试API接口功能
2. 及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力
3. 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可以同时发布API接口文档界面。不需要部署独立服务

Swagger2.0集成配置

Maven依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.jx.swagger</groupId>
    <artifactId>swagger_demo</artifactId>
    <version>1.0-SNAPSHOT</version>

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

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <spring-cloud.version>Finchley.SR2</spring-cloud.version>
    </properties>

    <dependencies>
        <!-- web starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- swagger接口依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger-ui依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- Devtools -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

编写Swagger Config添加到容器

@Configuration
@EnableSwagger2   // 开启Swagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.jx.api"))   // com.jx：生成api扫包的范围
                .paths(PathSelectors.any()).build();
    }

    // 创建api文档信息
    private ApiInfo apiInfo() {
        /*
         * title：文档标题
         * description：文档描述信息
         * termsOfServiceUrl：官方网址
         * version：版本号
         */
        return new ApiInfoBuilder().title("swagger auto build api document").description("swagger 自动生成文档")
                .termsOfServiceUrl("").version("1.0").build();
    }
}

然后在对应的Controller类上使用@Api和对应的方法上写@ApiOperation注解

@Api("Swagger demo控制器")
@RestController
public class SwaggerController {

    @ApiOperation("swagger演示接口")
    @GetMapping("/swaggerIndex")
    public String swaggerIndex() {
        System.out.println("swaggerIndex");
        return "";
    }
}

启动项目后访问：http://127.0.0.1:9090/swagger-ui.html#/swagger-controller 即可

Swagger设置参数

有的请求是带着参数的，那么Swagger怎样设置参数呢？

通过@ApiImplicitParam注解即可设置

@ApiOperation("swagger演示接口")
@ApiImplicitParam(name = "name", value = "用户名参数", required = true, dataType = "String")
@GetMapping("/swaggerIndex")
public String swaggerIndex(String name) {
    System.out.printf("name: %s", name);
    return name;
}

然后来到swagger的ui界面

点击Try it out

 

使用zuul + swagger管理整个微服务接口文档

在微服务中，每个服务单独集成Swagger，那么这样肯定是不好的，不方便管理，那么怎样将整个微服务中的Swagger进行合成，实现统一管理呢？

这就需要使用

1、Zuul + Swagger实现管理整个微服务的API文档了。

2、或者是使用Nginx + Swagger以项目不同区分跳转到不同的接口文档里面

在SpringBoot中是支持对Swagger的管理的，只需要Zuul网关添加对应的服务的Swagger文档即可

那么具体怎样做呢？

每个服务里面单独配置swagger

首先每个单独的服务都必须引入Maven依赖

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

application.yml配置扫包范围

swagger:
    base-package: com.jx.api

在启动类上配置@EnableSwagger2Doc注解以及@Api注解加以说明

@EnableSwagger2Doc
@Api("会员服务")
@SpringBootApplication
public class SwaggerDemoApplication {

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

zuul网关配置

引入Maven依赖

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

在启动类下中配置如下信息

@EnableZuulProxy
@EnableEurekaClient
@EnableSwagger2Doc  // 开启Swagger2文档
@SpringBootApplication
public class SpringCloudZullApplication {

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

    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {

        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList();
            // 这里的jx-member是随便写的，之后会在swagger的页面中出现一个下拉选框，选择的名字就是这个
            resources.add(swaggerResource("jx-member","/api-member/v2/api-docs", "2.0"));
            resources.add(swaggerResource("jx-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;
        }
    }

}

启动网关访问对应地址即可