Spring Cloud之Swagger2 API接口管理

快来打我* 2022-01-28 14:11 240阅读 0赞

# [Spring Cloud之Swagger2 API接口管理][Spring Cloud_Swagger2 API] #

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

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

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

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

API接口返回信息不明确

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

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

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

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

## Swagger具有以下优点 ##

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

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

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

<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>
    		
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    		
    		<dependency>
    			<groupId>org.springframework.cloud</groupId>
    			<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
    		</dependency>
    		
    		<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>

Controller:

package com.toov5.api;
    
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    
    @Api("swaggerdemo控制器")  //接口描述
    @RestController
    public class SwaggerController {
        @ApiOperation(value = "swagger演示接口")   //具体描述
        @GetMapping("/swaggerIndex")
        public String swaggerIndex() {
            
            return "swaggerIndex";
        }
    }

创建config包，并且贴入依赖：

@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("Toov5|微服务电商系统").description("demo")
                    .termsOfServiceUrl("http://www.itmayiedu.com")
                    // .contact(contact)
                    .version("1.0").build();
        }
    
    }

yml:

###服务启动端口号
    server:
      port: 6060
    ###服务名称
    spring:
        application:
            name: springboot-swagger

访问：

![1179709-20181117152715382-1994020188.png][]

传入参数型的接口：

package com.toov5.api;
    
    import org.aspectj.weaver.tools.Trace;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    
    @Api("swaggerdemo控制器")  //接口描述
    @RestController
    public class SwaggerController {
        @ApiOperation(value = "swagger演示接口")   //具体描述
        @GetMapping("/swaggerIndex")
        public String swaggerIndex() {
            
            return "swaggerIndex";
        }
        
        @ApiOperation(value = "获取会员信息接口")   //具体描述
        @ApiImplicitParam(name="userName",value="用户信息参数",required=true,dataType="String")  //传入的参数  ,描述 , 必须传递true , 类型String
        @GetMapping("/getMembe")
        public String getMember(String userName) {
            System.out.println(userName);
            return "userName"+userName;
        }
        
        
    }

点击try out

然后传入参数, excute执行一下

![1179709-20181117153853719-262678798.png][]

![1179709-20181117153836279-1343668532.png][]

[Spring Cloud_Swagger2 API]: https://www.cnblogs.com/toov5/p/9974147.html
[1179709-20181117152715382-1994020188.png]: /images/20220128/5ba4012dbaeb40a48336065447acd9aa.png
[1179709-20181117153853719-262678798.png]: /images/20220128/390be6e366754313934993e156bebd25.png
[1179709-20181117153836279-1343668532.png]: /images/20220128/d2d2c575aab847258602e3079143a335.png