Spring Boot与swagger集成构建API管理及测试

深藏阁楼爱情的钟 2022-03-17 03:22 170阅读 0赞

首先明白swagger是什么  [https://swagger.io/][https_swagger.io]

根据官网的介绍：   
Swagger Inspector：测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。

执行简单的API测试  
生成OpenAPI文档  
探索新的API功能  
我的理解Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说，Swagger是一个功能强大的接口管理工具，并且提供了多种编程语言的前后端分离解决方案。根据我的使用，当然我只是最简单的使用，我感觉Swagger有以下几个优点：

Swagger可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档。  
将前端后台分开，不会有过分的依赖。  
界面清晰，无论是editor的实时展示还是ui的展示都十分人性化，如果自己仅仅用markdown来编写，又要纠结该如何展现，十分痛苦。

下面直接使用springBoot +swagger2案例来进行展示

第一创建springBoot项目，可以网上进行模板创建[http://start.spring.io/][http_start.spring.io]

下面是我的项目结构

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70][]

第二下面是具体的

<?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>
 	<parent>
 		<groupId>org.springframework.boot</groupId>
 		<artifactId>spring-boot-starter-parent</artifactId>
 		<version>2.1.3.RELEASE</version>
 		<relativePath/> 
 	</parent>
 	<groupId>com.example</groupId>
 	<artifactId>springBoot-swagger</artifactId>
 	<version>0.0.1-SNAPSHOT</version>
 	<name>springBoot-swagger</name>
 	<description>Demo project for Spring Boot</description>
 
 	<properties>
 		<java.version>1.8</java.version>
 	</properties>
 
 	<dependencies>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter</artifactId>
 		</dependency>
 
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
 		</dependency>
 		
 
 		<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.6.1</version>
 </dependency>
 
 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.6.1</version>
 </dependency>
 
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 	</dependencies>
 
 	<build>
 		<plugins>
 			<plugin>
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-maven-plugin</artifactId>
 			</plugin>
 		</plugins>
 	</build>
 
 </project>

package com.example.domain;
    
    public class Book {
    	
    	private Long Id;
    
    	public Long getId() {
    		return Id;
    	}
    
    	public void setId(Long id) {
    		Id = id;
    	}
    
    	public Book(Long id) {
    		super();
    		Id = id;
    	}
    	
    	
    
    }

package com.example.config;
 
 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;
 
 /**
 * Title: SwaggerConfig
 * Description: Swagger2的配置管理类
 * Company: 
 * @author LYH
 * @date 2019年2月22日 上午10:34:04
 */
 @Configuration
 @EnableSwagger2
 public class SwaggerConfig {
 	
 	@Bean
 	public Docket createRestApi() {
 		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
 				.select()
 				.apis(RequestHandlerSelectors.basePackage("com"))
 				.paths(PathSelectors.any()).build();
 	}
 
 	private ApiInfo apiInfo() {
 		// TODO Auto-generated method stub
 		return new ApiInfoBuilder()
 				.title("Spring Boot 中使用Swagger2构建RESTful APIs")
 				.description("myapp")
 				.termsOfServiceUrl("http://www.baidu.com")
 				.version("1.0")
 				.build();
 	}
 
 }

package com.example.controller;
 
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.RestController;
 
 import com.example.domain.Book;
 
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiOperation;
 
 /**
 * Title: BookController
 * Description: 
 * Company: 
 * @author LYH
 * @date 2019年2月22日 上午10:49:54
 */
 @RestController
 @Api(tags = "BookController", description = "BookController | 通过书来测试Swagger")
 @RequestMapping(value = "/books")
 public class BookController {
 
 	Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long,Book>());
 	
 	@ApiOperation(value = "创建图书", notes="创建图书")
 	@ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
 	@RequestMapping(value = "", method = RequestMethod.POST)
 	public String postBook(@RequestBody Book book) {
 		books.put(book.getId(), book);
 		return "success";
 	}
 	
 	@ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息")
 @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")
 @RequestMapping(value = "/{id}", method = RequestMethod.GET)
 public Book getBook(@PathVariable Long id) {
 return books.get(id);
 }
 }

package com.example;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.annotation.ComponentScan;
    
    @SpringBootApplication
    @ComponentScan(basePackages = {"com"})
    public class SpringBootSwaggerApplication {
    
    	public static void main(String[] args) {
    		SpringApplication.run(SpringBootSwaggerApplication.class, args);
    	}
    
    }

第三步启动springBoot项目，浏览器访问地址[http://localhost:8080/swagger-ui.html\#/][http_localhost_8080_swagger-ui.html]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 2][]

点击 Try it out！之后将执行

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 3][]

点击get方法将获取刚刚创建的Book

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 4][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 5][]

到此项目就完成了，简单的完成了我们的目标。

[https_swagger.io]: https://swagger.io/
[http_start.spring.io]: http://start.spring.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70]: /images/20220317/5a1d00ba881842b1b27cde6900e2bc7c.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 1]: /images/20220317/0ca3ea51d6a84f4d9d201e7d2645fde2.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 2]: /images/20220317/02652d150c6b4564955d330320963af7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 3]: /images/20220317/1655b28453b44e5492cf77bdfb72267b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 4]: /images/20220317/4b42806baecc469f92e45a850a44bcaa.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODI3OTU3_size_16_color_FFFFFF_t_70 5]: /images/20220317/34a14f7fedbf4128a441c56e120da0d8.png