SpringCloud之使用Swagger生成微服务中API文档

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

来源：PC端、微信端、H5端、移动端（安卓和IOS端）

 

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

对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；

API接口返回信息不明确

大公司中肯定会有专门文档服务器对接口文档进行更新。

缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等

接口文档太多，不便于管理

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

 

Swagger具有以下优点

1.功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；

2.及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；

3.整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

 

Swagg  er 2.0 集成配置

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.0.5.RELEASE
         
    
    com.buba
    demo
    0.0.1-SNAPSHOT
    demo
    Demo project for Spring Boot

    
        1.8
        Greenwich.RELEASE
    

    
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
        
            org.springframework.cloud
            spring-cloud-starter-netflix-eureka-client
        
        
        
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        
    


    
        
            
                org.springframework.cloud
                spring-cloud-dependencies
                
                Finchley.RELEASE
                pom
                import
            
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

    
        
            spring-milestones
            Spring Milestones
            https://repo.spring.io/milestone
            
            
                false
            
        
    

写一个配置类,描述文档一些信息

package com.buba.configuration;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				// 扫包的范围,也就是把哪些包生成api文档
				.apis(RequestHandlerSelectors.basePackage("com.buba.controller")).paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {
		//title文档标题
		//description文档描述
		//termsOfServiceUrl自定义地址
		//version版本号
		return new ApiInfoBuilder().title("微服务电商系统").description("微服务swagger")
				.termsOfServiceUrl("http://www.buba.com")
				// .contact(contact)
				.version("1.0").build();
	}

}

随便写个controller接口,然后启动项目进行测试,启动后报的错不用管.

package com.buba.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Api("aaa")
@Controller
public class SwaggerController {

    //描述方法的
    @ApiOperation("方法一描述")
    //描述参数的  name参数名  value描述信息  required是否必填  dataType参数类型
    @ApiImplicitParam(name = "userName",value = "用户名参数",required = true,dataType = "String")
    @GetMapping("/swaggerIndex")
    public String swaggerIndex(String userName){
        System.out.println(userName);
        return "index";
    }
}

http://localhost:9090/swagger-ui.html访问这个路径就能看到api文档详细信息了

直接在这上面就可以测试