0
点赞
收藏
分享

微信扫一扫

项目管理.API生成和管理 Swagger

RJ_Hwang 2022-04-13 阅读 53
JavaSwaggerAPI

随着微服务，Restfull风格，富客户端，JS框架的发展。前后端分离成为趋势。这对前后端协同和项目管理都提出挑战。

  1. 后端的接口URL，参数，请求类型，参数的业务含义是什么
  2. 后端接口是否可以访问
  3. 后端接口变化后通知不及时导致前端访问出错
  4. 后端接口变化后，并没有更新API文档

等等。 为了解决这些问题，Swagger应用而生。下来就Swagger的使用和特点做详细介绍。

介绍

简单介绍

说简单一点，Swagger就是在Controller的方法上添加一些注解。启动后，可以通过URL访问API界面，即可获得接口信息，也可以通过这个接口调用测试。

总结：

  1. 生成API文档
  2. 进行接口测试

当然：如果后端修改了接口，但并没有修改对于的注解，访问也是有问题的。

官网

Swagger UI

组件介绍

Swagger是一组开源项目，其中主要要项目如下：

1.   Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2.   Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3.   Swagger-js: 用于JavaScript的Swagger实现。

4.   Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5.   Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6.   Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

HelloWord

第一个示例，该示例给予sprintboot，需支持WEB模块。  

POM

<?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>1.5.21.RELEASE</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.haiwei</groupId>
	<artifactId>haiwei-swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<!-- swagger dependency -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.2.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.2.2</version>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

配置Swagger2Congfig

说明：

  1. 该类跟Application同目录
  2. 修改controller包路径

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;

/**
 * Swagger2配置类 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2Congfig {
	
	/**
	 * 创建API应用 apiInfo() 增加API相关信息
	 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
	 * 本例采用指定扫描的包路径来定义指定要建立API的目录。
	 * @return
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				// 配置API扫描的包
				.apis(RequestHandlerSelectors.basePackage("com.haiwei.haiweiswagger.controller"))
				.paths(PathSelectors.any())
				.build();
	}

	/**
	 * 创建该API的基本信息（这些基本信息会展现在文档页面中） 访问地址：http://项目实际地址/swagger-ui.html
	 * @return
	 */
	private ApiInfo apiInfo() {
		// 配置界面的那些说明
		return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs")
				.description("更多请关注http://www.baidu.com")
				.termsOfServiceUrl("http://www.baidu.com")
				.contact("sunf")
				.version("1.0")
				.build();
	}
}

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。对应界面如下，自己进行对应吧。

添加注解 

  1. @Api 类级别，是group级别
  2. @ApiOperation 方法级别，对应的是URL
  3. @ApiImplicitParam 方法的入参
  4. @ApiResponse 方法的输出
@RestController
@RequestMapping("/demo1")
@Api(value="Demo1Controller-示例Demo控制器")
public class Demo1Controller {
	
	/**
	 * 测试方法
	 * 访问地址：http://localhost:8080/demo1/fun1?param=param111
	 * @param param
	 * @return
	 */
	@GetMapping("/fun1")
	@ApiOperation(value="测试方法1", notes="多余note")
    @ApiImplicitParam(paramType="query", name = "param", value = "用户参数", required = true, dataType = "String")
	@ApiResponse(message = "字符串1", code = 200)
	public String fun1(String param){
		return "结果11111：" + param;
	}
}

API访问

地址：http://localhost:8080/swagger-ui.html

界面：

接口测试

注解解析 

 @Api
@ApiOperation
@ApiImplicitParam
@ApiImplicitParams
@ApiResponse
@ApiResponses
@ApiModel
@ApiModelProperty
@ApiModelProperty


注意事项：如果不指定Http类型，默认是7中类型都支持

Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。

如上图：updatePassword()未指定requestMethod，结果生成了7条API信息。所以如果没有特殊需求，建议根据实际情况加上requestMethod。

 综合应用

Controller

@RestController
@RequestMapping("/user")
@Api(value="用户接口")
public class UserController {
	
	@PostMapping("/findUser")
	@ApiOperation(value="查询用户信息", notes="根据用户名，年龄等信息查询用户信息列表")
	@ApiImplicitParams({
		@ApiImplicitParam(paramType="query", name = "id", value = "请求标识", required = true, dataType = "String"),
	})
	@ApiResponses({
		@ApiResponse(code=201,message="成功1",response = UserVo.class),
		@ApiResponse(code=400,message="失败",response = UserVo.class)
	})
	public List<UserVo> findUser(@RequestParam String id, @RequestBody UserBo userBo){
		System.out.println(id);
		System.out.println(userBo.toString());
		
		List<UserVo> list = new ArrayList<UserVo>();
		
		UserVo e = new UserVo();
		e.setAge("age1");
		e.setUserName("userName1");
		e.setUserBo(userBo);
		list.add(e );
		
		UserVo e2 = new UserVo();
		e2.setUserBo(userBo);
		e2.setAge("age2");
		e2.setUserName("userName2");
		list.add(e2 );
		
		return list;
	}
}

Entity

@ApiModel(value = "用户BO")
public class UserBo {
    @ApiModelProperty(value="用户名" ,required=true)
	 private String userName;
    @ApiModelProperty(value="年龄" ,required=true)
	 private String age;
    // 省略getter & setter方法
}

@ApiModel(value = "用户VO")
public class UserVo {
    @ApiModelProperty(value="用户名1")
	 private String userName;
    @ApiModelProperty(value="年龄2")
	 private String age;
    @ApiModelProperty(value="UserBo2")
private UserBo userBo;
    // 省略getter & setter方法
}

API

刚进去界面

 注释查看

 访问

 小技巧

访问示例

swagger解析

首页/swagger-ui.html

地址：http://localhost:8080/swagger-ui.html

Jar包：springfox-swagger-ui

结构：

 首页信息接口/v2/api-docs

地址：http://localhost:8080/v2/api-docs

说明：get请求，直接地址栏访问即可

结果：

{
	"swagger": "2.0",
	"info": {
		"description": "更多请关注http://www.baidu.com",
		"version": "1.0",
		"title": "Spring Boot中使用Swagger2构建RESTful APIs",
		"termsOfService": "http://www.baidu.com",
		"contact": {
			"name": "sunf"
		},
		"license": {}
	},
	"host": "localhost:8080",
	"basePath": "/",
	"tags": [{
		"name": "demo2controller-示例demo控制器2",
		"description": "Demo2Controller-示例Demo控制器2"
	}, {
		"name": "demo1controller-示例demo控制器",
		"description": "Demo1Controller-示例Demo控制器"
	}],
	"paths": {
		"/demo1/fun1": {
			"get": {
				"tags": ["demo1controller-示例demo控制器"],
				"summary": "测试方法1",
				"description": "多余note",
				"operationId": "fun1UsingGET",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"name": "param",
					"in": "query",
					"description": "用户参数",
					"required": true,
					"type": "string"
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"type": "string"
						}
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				}
			}
		},
		"/demo2/fun1": {
			"get": {
				"tags": ["demo2controller-示例demo控制器2"],
				"summary": "测试方法2_1",
				"description": "多余note",
				"operationId": "fun2UsingGET",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"name": "param",
					"in": "query",
					"description": "用户参数",
					"required": true,
					"type": "string"
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"type": "string"
						}
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				}
			}
		}
	}
}

对应界面：

 插件加载入口

DocumentationPluginsBootstrapper.onApplicationEvent

参考：

Swagger使用指南__从头再来_的博客-CSDN博客_swagger使用

举报

相关推荐

Swagger管理api文档

java

Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api

swaggerspring mvcAPI文档文档自动化生成swagger-server-apiHtml/CSS前端开发

vue项目实战：api管理和封装

ios拦截器json编程语言

go使用swagger生成API文档

go swaggerkubernetes云计算

项目管理和产品管理

产品经理项目管理生命周期JavaScript前端开发

组织级项目管理和项目集、项目组合管理

项目管理项目集管理项目组合管理组织级项目管理组织战略系统/运维

最佳实践：Swagger 自动生成 Api 文档

微信小程序小程序

支持API文档生成，API管理工具：Apipost

API接口文档开发人员Java后端开发

项目沟通管理和干系人管理

项目沟通沟通管理项目干系人组织过程项目管理系统/运维

产品研发管理和研发项目管理

产品运营
0 条评论