您的位置:

c语言api接口文档生成工具,如何生成api文档

本文目录一览:

请问有没有用于API(C语言)的画界面,方便添加按钮的工具?或方法?

在 OFFICE VISO 2003中就有啊,你安装一个。打开VISIO,新建一个文档,在“软件”/“WINDOWS界面”中就用各种类型的控件和窗体的元素可以使用,就像设计UML图一样。

还在发愁写API文档?推荐一款阿里腾讯都在用的API管理神器

作为一个前后端分离模式开发的团队,我们经常会看到这样的场景:前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了?”,“接口怎么又不通了?”,“稍等,我调试下”,“你再试试..."。

那能不能写好接口文档,大家都按文档来开发?很难,因为写文档、维护文档比较麻烦,而且费时,还会经常出现 API 更新了,但文档还是旧的,各种同步不一致的情况,从而耽搁彼此的时间。

之前我们团队也遇到了同样的问题,那么作为研发团队的负责人,我是如何带领团队解决这个问题的呢?

方法其实很简单,如果能做到让写文档/维护文档这件事情的短期收益就能远高于付出的成本,那么所有问题都能迎刃而解,开发人员就会非常乐意去写接口文档。

要做到写文档和及时维护文档的短期收益就能远高于付出的成本,无非两个方向:

鉴于此,我们设想如果有一款工具做到以下这些是不是就非常爽了?

总结下来,我们需要的就是这么一款工具:

为此,我们几乎尝遍了市面上所有相关的工具,但是很遗憾,没有找到合适的。

于是,我们自己实现了一个Postman + Swagger + RAP + JMeter

这个工具就是 Apifox,经常很长一段时间不断更新迭代后,我们基本上完全实现了最初的设想,几乎完美解决了最开始遇到的所有问题,在公司内部大受欢迎。并且也形成了我们自己的最佳实践。

没错,现在我们已经将Apifox产品化对外服务了,你们团队也可以直接使用Apifox了。

官网:

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。

通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!

节省研发团队的每一分钟!

如果你认为 Apifox 只做了数据打通,来提升研发团队的效率,那就错了。Apifox 还做了非常多的创新,来提升开发人员的效率。

通常一个接口会有多种情况用例,比如 正确用例 参数错误用例 数据为空用例 不同数据状态用例。定义接口的时候定义好这些不同状态的用例,接口调试的时候直接运行,非常高效。

可以独立定义数据模型,接口定义时可以直接引用数据模型,数据模型之间也可以相互引用。同样的数据结构,只需要定义一次即可多处使用;修改的时候只需要修改一处,多处实时更新,避免不一致。

使用 Apifox 调试接口的时候,系统会根据接口文档里的定义,自动校验返回的数据结构是否正确,无需通过肉眼识别,也无需手动写断言脚本检测,非常高效!

Apifox 自动校验数据结构

设置断言:

Apifox 设置断言

运行后,查看断言结果:

先放一张图对比下 Apifox 和其他同类工具 零配置 mock 出来的数据效果:

Apifox Mock 数据结果对比同类工具

可以看出 Apifox 零配置 Mock 出来的数据和真实情况是非常接近的,前端开发可以直接使用,而无需再手动写 mock 规则。

「Apifox 如何做到高效率、零配置生成非常人性化的 mock 数据」

Apifox 项目可“在线分享” API 文档,分享出去的 API 文档可设置为公开或需要密码访问,非常方便与外部团队协作。

体验地址:

根据接口模型定义,自动生成各种语言/框架(如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等)的业务代码(如 Model、Controller、单元测试代码等)和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。

更重要的是:你可以通过自定义代码模板来生成符合自己团队的架构规范的代码,满足各种个性化的需求。

接口调试

Apifox 多种主题色可选

YAPI:从0搭建API文档管理工具

最近在找一款API文档管理工具,之前有用过Swagger、API Manager、Confluence,现在用的还是Confluence。

我个人一直不喜欢用Swagger,感觉“代码即文档”,让代码里的文档无处不在,已经对代码造成了一定的入侵了。API Manager就是一个纯API文档管理的工具了。Confluence是万能的,也是最简单的,支持各种插件在线安装,可以有各种布局,支持MD文档,也支持表格、代码块等。

最近看到一篇文章在说YAPI,就准备搭建一个试试效果如何。

YAPI是去哪儿网开源的一款API管理工具,理念如下:

特性:

选择YAPI试试手的原因是因为我看到了它支持MockServer,这样前端开发同学就不用等待后端同学了。主要是我也懒得搭建一套mock服务,有这样一款工具何乐而不为呢?所以今天就找了一台服务器安装了一下。考虑排版问题,就以图片形式放出来了。

nodeJS长期支持版本官网下载地址:,下载后执行如下命令:

nodeJS安装完毕。

YAPI安装,GitHub上已经有比较详细的文档了,地址:,这里说一下两种部署方式:

可视化部署:

yapi安装完毕,访问进行可视化配置一步一步往下走即可。

命令行部署(推荐方式):

yapi安装完毕,访问:{config.json中配置的port}即可访问。

node需要安装pm2模块,使用pm2模块后台运行yapi:

运行成功页面:

至此,YAPI就安装完毕了,简单实用一下还是不错的,因为是国产的,整体操作风格还是比较习惯的。在YAPI这里接口更改还有记录哦~

后面再慢慢体验这个里面的一些高级功能吧,比如MockServer、接口测试等功能。

大家还有什么更好用的API管理工具?你觉得一款优秀的API管理工具应该都有哪些必须的功能?欢迎推荐和讨论!

神器 SpringDoc 横空出世!最适合 SpringBoot 的API文档工具来了

之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库,上了下官网发现已经有接近两年没出新版本了!前几天升级了SpringBoot 2.6.x 版本,发现这个库的兼容性也越来越不好了,有的常用注解属性被废弃了居然都没提供替代!无意中发现了另一款Swagger库SpringDoc,试用了一下非常不错,推荐给大家!

SpringDoc简介

SpringDoc是一款可以结合SpringBoot使用的API文档生成工具,基于OpenAPI 3,目前在Github上已有1.7K+Star,更新发版还是挺勤快的,是一款更好用的Swagger库!值得一提的是SpringDoc不仅支持Spring WebMvc项目,还可以支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目,总之非常强大,下面是一张SpringDoc的架构图。

使用

接下来我们介绍下SpringDoc的使用,使用的是之前集成SpringFox的mall-tiny-swagger项目,我将把它改造成使用SpringDoc。

集成

首先我们得集成SpringDoc,在pom.xml中添加它的依赖即可,开箱即用,无需任何配置。

!--springdoc 官方Starter--org.springdocspringdoc-openapi-ui1.6.6

从SpringFox迁移

我们先来看下经常使用的Swagger注解,看看SpringFox的和SpringDoc的有啥区别,毕竟对比已学过的技术能该快掌握新技术;

接下来我们对之前Controller中使用的注解进行改造,对照上表即可,之前在@Api注解中被废弃了好久又没有替代的description属性终于被支持了!

/**

* 品牌管理Controller

* Created by macro on 2019/4/19.

*/@Tag(name ="PmsBrandController", description ="商品品牌管理")@Controller@RequestMapping("/brand")publicclassPmsBrandController{@AutowiredprivatePmsBrandService brandService;privatestaticfinalLogger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);@Operation(summary ="获取所有品牌列表",description ="需要登录后访问")@RequestMapping(value ="listAll", method = RequestMethod.GET)@ResponseBodypublicCommonResult getBrandList() {returnCommonResult.success(brandService.listAllBrand());    }@Operation(summary ="添加品牌")@RequestMapping(value ="/create", method = RequestMethod.POST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult createBrand(@RequestBodyPmsBrand pmsBrand) {        CommonResult commonResult;        int count = brandService.createBrand(pmsBrand);if(count ==1) {            commonResult = CommonResult.success(pmsBrand);            LOGGER.debug("createBrand success:{}", pmsBrand);        }else{            commonResult = CommonResult.failed("操作失败");            LOGGER.debug("createBrand failed:{}", pmsBrand);        }returncommonResult;    }@Operation(summary ="更新指定id品牌信息")@RequestMapping(value ="/update/{id}", method = RequestMethod.POST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult updateBrand(@PathVariable("id")Longid,@RequestBodyPmsBrand pmsBrandDto, BindingResult result) {        CommonResult commonResult;        int count = brandService.updateBrand(id, pmsBrandDto);if(count ==1) {            commonResult = CommonResult.success(pmsBrandDto);            LOGGER.debug("updateBrand success:{}", pmsBrandDto);        }else{            commonResult = CommonResult.failed("操作失败");            LOGGER.debug("updateBrand failed:{}", pmsBrandDto);        }returncommonResult;    }@Operation(summary ="删除指定id的品牌")@RequestMapping(value ="/delete/{id}", method = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult deleteBrand(@PathVariable("id")Longid) {        int count = brandService.deleteBrand(id);if(count ==1) {            LOGGER.debug("deleteBrand success :id={}", id);returnCommonResult.success(null);        }else{            LOGGER.debug("deleteBrand failed :id={}", id);returnCommonResult.failed("操作失败");        }    }@Operation(summary ="分页查询品牌列表")@RequestMapping(value ="/list", method = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult listBrand(@RequestParam(value ="pageNum", defaultValue ="1")@Parameter(description ="页码")Integer pageNum,@RequestParam(value ="pageSize", defaultValue ="3")@Parameter(description ="每页数量")Integer pageSize) {        List brandList = brandService.listBrand(pageNum, pageSize);returnCommonResult.success(CommonPage.restPage(brandList));    }@Operation(summary ="获取指定id的品牌详情")@RequestMapping(value ="/{id}", method = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult brand(@PathVariable("id")Longid) {returnCommonResult.success(brandService.getBrand(id));    }}

接下来进行SpringDoc的配置,使用OpenAPI来配置基础的文档信息,通过GroupedOpenApi配置分组的API文档,SpringDoc支持直接使用接口路径进行配置。

/**

* SpringDoc API文档相关配置

* Created by macro on 2022/3/4.

*/@ConfigurationpublicclassSpringDocConfig{@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI()                .info(newInfo().title("Mall-Tiny API")                        .description("SpringDoc API 演示")                        .version("v1.0.0")                        .license(newLicense().name("Apache 2.0").url("")))                .externalDocs(newExternalDocumentation()                        .description("SpringBoot实战电商项目mall(50K+Star)全套文档")                        .url(""));    }@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder()                .group("brand")                .pathsToMatch("/brand/**")                .build();    }@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder()                .group("admin")                .pathsToMatch("/admin/**")                .build();    }}

结合SpringSecurity使用

由于我们的项目集成了SpringSecurity,需要通过JWT认证头进行访问,我们还需配置好SpringDoc的白名单路径,主要是Swagger的资源路径;

/**

* SpringSecurity的配置

* Created by macro on 2018/4/26.

*/@Configuration@EnableWebSecurity@EnableGlobalMethodSecurity(prePostEnabled = true)public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity httpSecurity) throws Exception {httpSecurity.csrf()// 由于使用的是JWT,我们这里不需要csrf.disable().sessionManagement()// 基于token,所以不需要session.sessionCreationPolicy(SessionCreationPolicy.STATELESS).and().authorizeRequests().antMatchers(HttpMethod.GET,// Swagger的资源路径需要允许访问"/","/swagger-ui.html","/swagger-ui/","/*.html","/favicon.ico","/**/*.html","/**/*.css","/**/*.js","/swagger-resources/**","/v3/api-docs/**").permitAll().antMatchers("/admin/login")// 对登录注册要允许匿名访问.permitAll().antMatchers(HttpMethod.OPTIONS)//跨域请求会先进行一次options请求.permitAll().anyRequest()// 除上面外的所有请求全部需要鉴权认证.authenticated();            }}

然后在OpenAPI对象中通过addSecurityItem方法和SecurityScheme对象,启用基于JWT的认证功能。

/**

* SpringDoc API文档相关配置

* Created by macro on 2022/3/4.

*/@ConfigurationpublicclassSpringDocConfig{privatestaticfinalString SECURITY_SCHEME_NAME ="BearerAuth";@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI()                .info(newInfo().title("Mall-Tiny API")                        .description("SpringDoc API 演示")                        .version("v1.0.0")                        .license(newLicense().name("Apache 2.0").url("")))                .externalDocs(newExternalDocumentation()                        .description("SpringBoot实战电商项目mall(50K+Star)全套文档")                        .url(""))                .addSecurityItem(newSecurityRequirement().addList(SECURITY_SCHEME_NAME))                .components(newComponents()                                .addSecuritySchemes(SECURITY_SCHEME_NAME,newSecurityScheme()                                                .name(SECURITY_SCHEME_NAME)                                                .type(SecurityScheme.Type.HTTP)                                                .scheme("bearer")                                                .bearerFormat("JWT")));    }}

测试

接下来启动项目就可以访问Swagger界面了,访问地址:

我们先通过登录接口进行登录,可以发现这个版本的Swagger返回结果是支持高亮显示的,版本明显比SpringFox来的新;

然后通过认证按钮输入获取到的认证头信息,注意这里不用加bearer前缀;

之后我们就可以愉快地访问需要登录认证的接口了;

看一眼请求参数的文档说明,还是熟悉的Swagger样式!

常用配置

SpringDoc还有一些常用的配置可以了解下,更多配置可以参考官方文档。

springdoc:swagger-ui:# 修改Swagger UI路径path:/swagger-ui.html# 开启Swagger UI界面enabled:trueapi-docs:# 修改api-docs路径path:/v3/api-docs# 开启api-docsenabled:true# 配置需要生成接口文档的扫描包packages-to-scan:com.macro.mall.tiny.controller# 配置需要生成接口文档的接口路径paths-to-match:/brand/**,/admin/**

总结

在SpringFox的Swagger库好久不出新版的情况下,迁移到SpringDoc确实是一个更好的选择。今天体验了一把SpringDoc,确实很好用,和之前熟悉的用法差不多,学习成本极低。而且SpringDoc能支持WebFlux之类的项目,功能也更加强大,使用SpringFox有点卡手的朋友可以迁移到它试试!

参考资料

项目地址:

官方文档:

项目源码地址