2.接口相关工具
2.1API接口文档利器:Swagger
2.1.1Swagger介绍
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
(https://swagger.io/)。 它的主要作用是:
-
使得前后端分离开发更加方便,有利于团队协作
-
接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
-
功能测试
Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox。通过在项目中引入Springfox ,即可非常简单快捷的使用Swagger。
2.1.2SpringBoot集成Swagger
-
在huiminpay-common项目中添加依赖,只需要在huiminpay-common中进行配置即可,因为其他微服务工程都直接或间接依赖huiminpay-common。
<!-- Swagger依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> </dependency>
-
在huiminpay-merchant-application工程的config包中添加一个Swagger配置类
package com.huiminpay.merchant.config;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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;
@Configuration
//此注解控制配置类是否生效,意思是当配置文件中prefix.value的值==havingValue的值则生效,否则无效
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
// 要扫描的API(Controller)基础包,注意要修改成自己项目的包路径
.apis(RequestHandlerSelectors.basePackage("com.huiminpay.merchant.controller"))
//过滤什么请求
.paths(PathSelectors.any())
.build();
}
/**
* 构建API基本信息
*/
private ApiInfo buildApiInfo() {
//联系信息
Contact contact = new Contact("开发者", "", "");
return new ApiInfoBuilder()
.title("惠民支付-商户应用API文档")
.description("")
.contact(contact)
.version("1.0.0").build();
}
}
- 添加SpringMVC配置类:WebMvcConfig,让外部可直接访问Swagger文档
package com.huiminpay.merchant.config;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* @author Administrator
* @version 1.0
**/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
/**
* 添加静态资源文件,外部可以直接访问地址
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");//解决swagger2中js无法访问
}
}
2.1.3Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口文档,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数的描述信息
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数的描述信息
@ApiImplicitParam属性:
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 。只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
上边的属性后边编写程序时用到哪个我再详细讲解,下边写一个swagger的简单例子,我们在MerchantController 中添加Swagger注解,代码如下所示:
@ApiOperation("测试")
@GetMapping("/hello/{name}")
public String hello(@PathVariable("name") String name) {
return "hello," + name;
}
@ApiOperation("测试")
@PostMapping("/hi/{name}")
public String hi(@PathVariable("name") String name) {
return "hi," + name;
}
2.1.4Swagger测试
-
启动商户应用和商户中心服务,访问:http://localhost:57010/merchant/swagger-ui.html
-
点击其中任意一项即可打开接口详情,如下图所示:
-
点击“Try it out”开始测试,并录入参数信息,然后点击“Execute"发送请求,执行测试返回结果:“hi,李四”
Swagger生成API文档的工作原理:
1、huiminpay-merchant-application启动时会扫描到SwaggerConfiguration类
2、在此类中指定了扫描包路径com.huiminpay.merchant.controller,会找到在此包下及子包下标记有
@RestController注解的controller类
3、根据controller类中的Swagger注解生成API文档
**注意:**如果第2步扫描包路径有误则会出现swagger页面正常显示,但是没有接口信息的情况。
2.2 接口调试利器Postman
Postman是一款功能强大的http接口测试工具,使用Postman可以完成http各种请求的功能测试。作为服务器端开发人员,当一个业务功能开发完毕后,应该用Postman进行功能测试。
1、请自行在本机安装Postman
2、新建集合(建议一个微服务新建一个对应的集合):惠民支付-商户应用
3、在惠民支付-商户应用集合中新建请求Add Request,并录入请求信息
填写新建商户接口地址和请求类型后,点击Send发送请求:文章来源:https://www.toymoban.com/news/detail-668166.html
小技巧:每个测试都可以进行保存(Ctrl+S),以便于后续使用。文章来源地址https://www.toymoban.com/news/detail-668166.html
到了这里,关于API接口文档利器:Swagger 和 接口调试利器:Postman的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!