听说你Rpc服务需要写一份接口文档？

Fmbah安徐正静
489 阅读3分钟

听说你Rpc服务需要写一份接口文档？

Hi，听油们～Java服务端的架构发展史我们不进行过多的讲述，毕竟有很多前辈在网上也有很多精细的介绍，目前用来管理流量的网关架构ShenYu，当使用网关架构统一流量请求时，对开发来讲第一个问题时，以前的rpc服务仅暴露给业务方调用，现在省去了业务方这一层，而是由底层服务直接提供对应的数据作为业务支撑，这样做的好处显而易见，不仅可以少一个人开发，工作量也随之降低不少；可恶的程序猿们啊，真鸡儿的卷了您内！可是以前写接口文档的时候分为两派，一派是说手写接口文档，每当变更的时候，代码/文档各改一遍（或者使用一些额外的插件来读取javadoc内容来生成文档，不过这也是需要手工处理）；另一派是在代码里将接口文档内容写好，然后通过自动方式将接口内容同步过去，我个人偏向第二种方式，虽然在代码里写了一坨和业务无关的内容，但实际来讲也强制开发将备注内容写的较为完善，便于后续维护

那我使用的接口文档框架Swagger，如果说想在接口层可以生成接口文档，原有的框架则支持起来相对较弱，然后我也是偶然搜索了下万能的GitHub，恰巧发现前辈已经有对接口层文档做了支持，那么这里列下前辈的链接Swagger-Dubbo，前辈在这里实现的功能有点多，而实际我并不需要类似dubbo调用之类的内容，我这里就做了个简单的换汤不换药的包装包装后的地址，然后也顺便将使用方式总结了下，如果有需要的，可以直接使用起来～

使用方式

  1. git clone github.com/a807966224/…
  2. cd swagger-dubbo-v2
  3. mvn clean install
  4. 将target下的jar包引入到你的项目里
  5. 听油们，瞧重点了哈～
    • 应用配置
    @Value("${server.servlet.context-path:}")
// 应用访问路径，暴露给ShenYu的路径
private String contextPath;
@Value("${swagger.dubbo.enable:true}")
// 是否开启，生产环境填写false
private boolean enable = true;
    • 接口层支持Swagger注解
    compileOnly "io.swagger:swagger-annotations:1.6.6"
    • 应用中引入swagger-dubbo支持，这里没有单独列要引入第四步骤的包哈，你要记得自己引入进来
    compile "io.swagger:swagger-core:1.5.16"

    import com.jx.config.EnableDubboSwagger;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableDubboSwagger
public class SwaggerDubboConfig {
}
    • 代码层新增Swagger注解，因为我仅将使用频繁的注解进行了支持，如果有需要可以进行二次开发
    1. 类上增加@Api(tags={"接口目录名称"})，用来标识当前文档在哪个目录下
2. 方法上增加@ApiOperation(nickname = "请求路径", value = "接口描述", httpMethod = "POST", consumes = "application/json")
3. 方法参数&返回值类上增加@ApiModel(value = "请求｜响应描述")
4. 方法参数&返回值类的字段属性增加@ApiModelProperty(value = "字段描述", example = "举例")

耨耨耨，就这些哈，如果有不理解的地方欢迎QA～

avatar
文章
阅读
粉丝