Api接口管理SrpingCloud之Swagger2

背景

       随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

传统的API文档编写存在以下几个痛点：

• 对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时
• API接口返回信息不明确
• 缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
• 接口文档太多，不便于管理

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点：

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

项目搭建

1、pom文件引入

    <!-- 管理依赖 -->
	<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>

2、Swagger配置类

@Configuration
//用@Configuration注解该类，等价于XML中配置beans；
// 用@Bean标注方法等价于XML中配置bean。
@EnableSwagger2
public class SwaggerConfig {
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				// 自行修改为自己的包路径
				.apis(RequestHandlerSelectors.basePackage("com.springcloud.swagger")).paths(PathSelectors.any())
				.build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("api").description("restful")
				// 服务条款网址
				// .termsOfServiceUrl("http://blog.csdn.net/forezp")
				.version("1.0")
				// .contact(new Contact("帅呆了", "url", "email"))
				.build();
	}
}

3、启动项

@SpringBootApplication
//表示开启Swagger
@EnableSwagger2
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

4、访问Swagger主页

http://localhost:8080/swagger-ui.html

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

使用Zuul+Swagger实现管理整个微服务API服务。

会员项目和订单项目pom文件新增

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

配置文件

在会员服务配置文件中新增

swagger:
  base-package: com.springcloud.applunmember

订单服务配置文件中新增

swagger:
  base-package: com.springcloud.applunorder

会员服务启动项

@RestController
@EnableEurekaClient
@SpringBootApplication
@EnableSwagger2Doc
@Api("会员服务接口")
public class AppLunMemberApplication {
    @Value("${server.port}")
    private String serverPort;
    @RequestMapping("/")
    public String index() {
        return "我是member会员服务" + serverPort;
    }
    @ApiOperation("获取会员相关信息")
    @ApiImplicitParam(name = "id", value = "ID", paramType = "path", required = true, dataType = "Integer")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public String getStudent(@PathVariable int id) {
        return "id:"+id;
    }
    public static void main(String[] args) {
        SpringApplication.run(AppLunMemberApplication.class, args);
    }
}

订单服务启动项

@RestController
@EnableEurekaClient
@SpringBootApplication
@EnableSwagger2Doc
@Api("订单服务接口")
public class AppLunOrderApplication {
    @RequestMapping("/")
    public String index() {
        return "我是订单服务项目";
    }
    public static void main(String[] args) {
        SpringApplication.run(AppLunOrderApplication.class, args);
    }
}

Zuul网关服务启动项

@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class ZuulApplication {
    public static void main(String[] args) {
        SpringApplication.run(ZuulApplication.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-lun-member", "/api-member/v2/api-docs", "2.0"));
            resources.add(swaggerResource("app-lun-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;
        }
    }

}