easy-swagger

最新推荐文章于 2024-01-16 19:00:00 发布

小雨的光

最新推荐文章于 2024-01-16 19:00:00 发布

阅读量786

点赞数 1

分类专栏： easy-develop 文章标签： easy-swagger swagger 接口文档

本文链接：https://blog.csdn.net/qq_28802119/article/details/96880977

版权

easy-develop 专栏收录该内容

19 篇文章 1 订阅

订阅专栏

为什么要选择easy-swagger？

日常开发中，接口文档几乎是必不可少的一环，靠程序员自己维护接口文档经常出现的几个问题是：需要额外花时间编写文档，从而导致更新不及时，维护又麻烦。到最后，除非强制要求，否则接口文档几乎不可用了。

基于注解生成接口文档的swagger一开始的确缓解了程序员和接口文档之间的矛盾，但是过分的植入注解导致的注解泛滥又让很多人不得不放弃这种方式，开始转向读取注释的方式来生成文档。

然而基于注释的方式存在的问题是，如果程序员不及时更新注释又会导致接口文档不可用（比如参数变更）。而且打包之后注释就没了，强行将注释打包到jar的方式又会增加jar包的体积。

相信经历了这些的你一定希望出现一个对程序员和接口文档都友好的方式，这就是选择easy-swagger的理由。

介绍

easy-swagger的主要目标是解决前后端交互需要编写文档的困扰，服务对象是前端研发人员。如果你一直被写文档的恐惧支配，如果你怀揣着减少编写文档工作的梦想，那么，请你收下这份礼物——easy-swagger。第一、简单易上手，配置简单，即插即用；第二、写代码时顺手写文档，不需要占用很大篇幅，简洁不啰嗦；第三、容易维护，只需要修改极少的东西就可以完成文档的更新；第四、就算你完全懒得在代码中加入一个额外注解，它也能自动产出高可用的文档.；第五、超强悍的微服务文档聚合能力。

基础功能

1. 引用

新建maven项目引入easy-swagger依赖(点击最新版本地址查看最新版本)

<dependency>
    <groupId>io.github.xiaoyudeguang</groupId>
    <artifactId>easy-swagger</artifactId>
    <version>最新版本</version>
</dependency>

2. 编码

import com.zlyx.easycore.tool.Console;
import com.zlyx.easyswagger.annotations.SpringController;
import com.zlyx.easyswagger.annotations.SpringMapping;

import io.swagger.annotations.ApiParam;

@SpringController(value = "demoController", todo = { "easy-swagger使用示例" })
public class DemoController {

	@SpringMapping(value = "test", todo = { "easy-swagger示例方法" }, notes = "随便写点啥，当做方法简介吧")
	public Object test(String name, int age) {
		Console.log(name, age);
		return "easy-swagger is an good tool!";
	}
}

3. 效果（打开浏览器访问：http://localhost:8080/docs.html）

4. 修改默认配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.zlyx.easyswagger.config.ApiConfiguration;

@Configuration
public class SwaggerConfiguration {

	@Bean
	public ApiConfiguration configApi() {
		return new ApiConfiguration()
				.setEnabled(true) //是否启用
				.setBasePath("/ttt") //设置请求路径前缀(可选配置)
				.setHost("http://localhost/8080") //配置域名(可选配置)
				.setShowPath(true) //文档中是否显示包路径
				.setLog(true) //是否显示切面日志
				.setVersion("1.1.0") //版本号
				.setUrl("https://gitee.com/xiaoyudeguang/easy-swagger") //项目托管地址
		;
	}
}

5. 自定义配置方式

如果easy-swagger配置Docket的方式无法满足你的需要，你可以在配置类中用自己习惯的方式添加Docket的Bean，像这样：

	@Bean
	public Docket configDocket (){
		return new Docket(DocumentationType.SWAGGER_2).enable(false);
	}

需要注意的事，这种方式配置Docket需要将enable属性设置为false，否则你将不能很好地使用easy-swagger。

说出来你可能不信，你已经成功的学会如何使用easy-swagger了。？？？没错，这就是全部使用步骤了。如果不是很有耐心往下看的话，你已经可以出师了。easy-swagger采用了大量自动配置的方案来优化使用体验。如果你想体验它的高级功能，那么，请接着往下看。

高级功能

1. 兼容原生swagger

为了适应大多数项目已经引入了swagger注解的情况，easy-swagger对swagger注解做了兼容。对于之前的代码你不需要做任何修改就可以同样体验到easy-swagger的能力。比如，下面的代码和上面示例中的代码具有一致的效果。

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.zlyx.easycore.tool.Console;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Api("easy-swagger使用示例")
@RestController
@RequestMapping("demoController")
public class DemoController {

	@ApiOperation("easy-swagger示例方法")
	@RequestMapping(value = "test")
	public Object test(String name, String age) {
		Console.log(name, age);
		return "easy-swagger is an good tool!";
	}
}

2. 分组功能

easy-swagger对swagger做了一层封装，你仍然可以使用swagger的分组功能。

编码示例

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.zlyx.easyswagger.config.ApiConfiguration;

@Configuration
public class SwaggerConfiguration {

	@Bean
	public ApiConfiguration configApi() {
		return new ApiConfiguration()
			.addApiProperties("按包分组", "按包分组", "按包分组", "com.zlyx.easytest.demo")
			.addApiProperties("按请求路径分组", "按请求路径分组", "按请求路径分组", "com.zlyx.easytest", "/demo/**")
			.addApiProperties("按包和请求路径分组", "按包和请求路径分组", "按包和请求路径分组", "com.zlyx.easytest.demo", "/demo/**");
	}
}

效果展示

3. 微服务聚合功能

相信微服务是目前大多数程序的选择。之前，如果需要聚合多个微服务程序的文档，微服务网关是必须的选择。作者也尝试过这种方式。但是，微服务网关的实现方式实在是让人痛苦不堪，一大堆的配置绕来绕去，我的天。我就是想看个文档，至于这么复杂么？

对于easy-swagger来说，你不需要额外的工作就可以达到聚合文档的目的。具体步骤如下：

（1）假设本地已经启动了两个微服务程序（需要引入easy-swagger），端口分别是8081和8082。我们修改8080端口对应的服务的配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.zlyx.easyswagger.config.ApiConfiguration;

@Configuration
public class SwaggerConfiguration {

	@Bean
	public ApiConfiguration configApi() {
		return new ApiConfiguration().addUrls("http://localhost:8081", "http://localhost:8082");
	}
}

通过上面代码，你已经把本地的8081和8082两个端口的微服务文档聚合进来了。打开8080端口的文档浏览器地址你可以在右上角的下拉框里找到8081和8082两个端口的接口文档。

（2）通过（1）中的配置，8081和8082端口的接口文档已经聚合到了8080端口的微服务中，但是，这种方式只能聚合先于自己启动的微服务。所以，需要被聚合的微服务在自己启动时，主动去8080端口的服务注册自己。打开8081和8082端口对应的服务，修改配置：

package com.zlyx.easytest.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.zlyx.easyswagger.config.ApiConfiguration;

@Configuration
public class SwaggerConfiguration {

	@Bean
	public ApiConfiguration configApi() {
		return new ApiConfiguration().setManagerUrl("http://localhost:8080");
	}
}

有了这个配置，8081端口和8082端口的服务就会在自己启动时主动注册到8080端口的服务。