Swagger接口管理

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

• 传统的API文档编写缺点

1. 对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；API接口返回信息不明确
2. 缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
3. 接口文档太多，不便于管理 
    
    所以:  为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。
    

• Swagger具有以下优点

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

• 使用springboot整合Swagger

1. 创建springboot项目，在pom.xml添加依赖 
    

   <!-- 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>

2. 在application.yml配置端口号和服务名 
    

   server:
     port: 8300
   spring:
     application:
       name: app-basic-swagger
   

3. 创建SwaggerConfig.java
    

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   /**
    * Create by wangxb
    * 2019-08-24 17:26
    */
   @Configuration    //  声明这是一个配置类
   @EnableSwagger2  //   表示开启swagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                   // 配置api的扫包范围
                   .apis(RequestHandlerSelectors.basePackage("com.basic.api")).paths(PathSelectors.any()).build();
       }
   
       /**
        * 生成api接口文档的信息    标题，说明，网址，作者信息, 版本号
        * @return
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("测试商城")//标题
                   .description("来一来，看一看咯")//描述
                   .termsOfServiceUrl("http://www.baidu.com")// 地址
                   .contact(new Contact("xiaobo", "https://blog.csdn.net/xiaobo5264063/article/details/100055009", "1115264064@qq.com"))// 作者信息
                   .version("1.0")//版本号
                   .build();
       }
   
   }

4. 在项目com.basic.api包下创建OrderController.java
    

   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiParam;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestParam;
   import org.springframework.web.bind.annotation.RestController;
   import java.util.ArrayList;
   import java.util.List;
   
   /**
    * Create by wangxb
    * 2019-08-24 17:31
    */
   @Api(value="aaaa",description="订单相关信息接口")
   @RestController
   public class OrderController {
   
       @GetMapping("/findAll")
       @ApiOperation(value="获取所有订单",notes="获取所有订单，无需参数")
       public List<String> findAll(){
           List<String> lists = new ArrayList<String>();
           for(int i=0; i<5; i++) {
               lists.add(i+"");
           }
           return lists;
       }
       @GetMapping("/findOne")
       @ApiOperation(value="根据订单号获取订单",notes="需要传入订单id")
       public String findOne(@RequestParam("id") String id){
           //查出的所有部门信息
           return id+"--123";
       }
   
       // @ApiImplicitParam(name="title", value="订单名称", required = true, type = "String")
       @PostMapping("/findByName")
       @ApiOperation(value="根据订单名称获取订单",notes="需要传入订单名称")
       public String findByName(@ApiParam(value = "订单名称", required = true) @RequestParam String title){
           System.out.println(title);
           return title+"--123";
       }
   
   }

   
    
5. 启动项目
    
    

   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   
   /**
    * Hello world!
    *
    */
   @SpringBootApplication
   public class AppSwagger
   {
       public static void main( String[] args )
       {
           SpringApplication.run(AppSwagger.class, args);
       }
   }

6. 测试
    
    测试地址: http://localhost:8300/swagger-ui.html
     
    
7. 测试结果
    
    
    

• springcloud整合swagger
   
   
   
   如图： 在会员服务和订单服务都集成swagger，zuul集成和配置swagger相关配置，在由zuul来帮我们转发不同的swagger文档
   
   

1. 引入swagger依赖
    在会员、订单、网关服务中引入依赖

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

2. 配置扫包范围
    在会员和订单服务中application.yml
    

   ## swagger文档，扫包范围
   swagger:
     base-package: com.basic.api

    

3. 启动类中添加注解 
    

   @EnableSwagger2Doc

   
    
4. 网关启动类
    

   @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-basic-order   /api-member/是zuul的application.yml配置服务转发地址
   			resources.add(swaggerResource("app1", "/api-member/v2/api-docs", "2.0"));
   			resources.add(swaggerResource("app2", "/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;
   		}
   	}
   
   }
   

5. 启动测试
    
    http://127.0.0.1:8300/swagger-ui.html