微信公众平台开发(13)--使用Swagger便于接口调试

淩亂°似流年 2022-08-28 09:53 122阅读 0赞

***[点此查看全部文字教程、视频教程、源代码][Link 1]***

### 本文目录 ###

*  1. 背景
 *  2. 配置pom
 *  3. 添加配置类
 *  4. 为控制器添加注解
 *  5. 调用测试
 *  6. 小结

# 1. 背景 #

在之前的示例中，我们都是通过访问URL发起测试的，这种方式比较麻烦。

我们可以在SpringBoot中引入Swaager，这样打开Swagger页面就可以直接可视化调试了。

# 2. 配置pom #

在pom.xml中添加如下配置：

<dependency>
       		<groupId>io.springfox</groupId>
       		<artifactId>springfox-swagger2</artifactId>
       		<version>2.9.2</version>
       	</dependency>
       	
       	<dependency>
       		<groupId>io.springfox</groupId>
       		<artifactId>springfox-swagger-ui</artifactId>
       		<version>2.9.2</version>
       	</dependency>

# 3. 添加配置类 #

通过配置类启用Swagger，并且配置一些基本信息。

@Configuration // 告诉Spring容器，这个类是一个配置类，Spring容器得采用这个类的配置
    @EnableSwagger2 // 启用Swagger2功能
    public class SwaggerConfig {
        
    	/**
    	 * 配置Swagger2相关的bean
    	 */
    	@Bean
    	public Docket createRestApi() {
        
    		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("cn"))// com包下所有API都交给Swagger2管理
    				.paths(PathSelectors.any()).build();
    	}
    
    	/**
    	 * 此处主要是API文档页面显示信息
    	 */
    	private ApiInfo apiInfo() {
        
    		return new ApiInfoBuilder().title("微信接入API") // 标题
    				.description("微信公众号、企业微信、微信支付API") // 描述
    				.termsOfServiceUrl("https://studyingpanda.blog.csdn.net/") // 服务网址
    				.version("1.0") // 版本
    				.build();
    	}
    }

# 4. 为控制器添加注解 #

依次为之前的自定义菜单、用户管理、客服消息控制器类及方法添加注解，从而生成可视化的API入口。

注意此处为了减少生成的方法数量，将`@RequestMapping`改为了`@PostMapping`。

@Api(tags = "自定义菜单API")
    @RestController
    public class MenuController {
        
    	@Autowired
    	private WxMpService wxMpService;
    
    	@ApiOperation(value = "获取自定义菜单")
    	@PostMapping("/menuGet")
    	public WxMpMenu menuGet() throws WxErrorException {
        
    		WxMpMenu wxMpMenu = wxMpService.getMenuService().menuGet();
    		return wxMpMenu;
    	}
    
    	@ApiOperation(value = "删除自定义菜单")
    	@PostMapping("/menuDelete")
    	public boolean menuDelete() throws WxErrorException {
        
    		wxMpService.getMenuService().menuDelete();
    		return true;
    	}
    
    	@ApiOperation(value = "创建自定义菜单")
    	@PostMapping("/menuCreate")
    	public boolean menuCreate() throws WxErrorException {
        
    		// 菜单
    		List<WxMenuButton> buttons = new ArrayList<WxMenuButton>();
    		WxMenuButton btn1 = new WxMenuButton();
    		btn1.setType("click");
    		btn1.setName("查询城市");
    		btn1.setKey("QUERY_CITY");
    		WxMenuButton btn2 = new WxMenuButton();
    		btn2.setType("view");
    		btn2.setName("跳转网页");
    		btn2.setUrl("http://www.csdn.net");
    		buttons.add(btn1);
    		buttons.add(btn2);
    		// 创建
    		WxMenu wxMenu = new WxMenu();
    		wxMenu.setButtons(buttons);
    		String re = wxMpService.getMenuService().menuCreate(wxMenu);
    		System.out.println(re);
    		return true;
    	}
    }

@Api(tags = "用户管理API")
    @RestController
    public class UserController {
        
    	@Autowired
    	private WxMpService wxMpService;
    
    	@ApiOperation(value = "获取用户列表")
    	@PostMapping("/userList")
    	public WxMpUserList userList() throws WxErrorException {
        
    		WxMpUserList wxUserList = wxMpService.getUserService().userList(null);
    		return wxUserList;
    	}
    
    	@ApiOperation(value = "获取用户信息")
    	@PostMapping("/userInfo")
    	public WxMpUser userInfo(@RequestParam("openid") String openid) throws WxErrorException {
        
    		String lang = "zh_CN"; // 语言
    		WxMpUser user = wxMpService.getUserService().userInfo(openid, lang);
    		return user;
    	}
    
    	@ApiOperation(value = "更新用户备注名")
    	@PostMapping("/userUpdateRemark")
    	public boolean userUpdateRemark(@RequestParam("openid") String openid, @RequestParam("remark") String remark) throws WxErrorException {
        
    		wxMpService.getUserService().userUpdateRemark(openid, remark);
    		return true;
    	}
    }

@Api(tags = "客服消息API")
    @RestController
    public class KefuMessageController {
        
    	@Autowired
    	private WxMpService wxMpService;
    
    	@ApiOperation(value = "更新用户备注名")
    	@PostMapping("/sendMessage")
    	public boolean sendMessage(@RequestParam("openid") String openid, @RequestParam("content") String content) throws WxErrorException {
        
    		WxMpKefuMessage message = WxMpKefuMessage.TEXT().toUser(openid).content(content).build();
    		wxMpService.getKefuService().sendKefuMessage(message);
    		return true;
    	}
    }

# 5. 调用测试 #

启动项目，访问`http://127.0.0.1/wx-server/swagger-ui.html`，然后选择一个接口点击即可测试。  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA54aK54yr5aSn5ZOl5aSn_size_20_color_FFFFFF_t_70_g_se_x_16]  
访问结果可视化显示如下：  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA54aK54yr5aSn5ZOl5aSn_size_20_color_FFFFFF_t_70_g_se_x_16 1]

# 6. 小结 #

用了Swagger之后，测试方便了很多，不需要再手工构建URL测试了，直接点击按钮即可。

另外如果有参数，也可以在界面上输入，很方便。

[Link 1]: https://studyingpanda.blog.csdn.net/article/details/105329926
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA54aK54yr5aSn5ZOl5aSn_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220828/3b1e2e48a7064925bb74e2bf66f4bb55.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA54aK54yr5aSn5ZOl5aSn_size_20_color_FFFFFF_t_70_g_se_x_16 1]: /images/20220828/107aac7375d2492badf41cf2706a7d5e.png