本篇文章给大家谈谈支持api接口的在线文档,以及提供api接口的平台对应的知识点,希望对各位有所帮助,不要忘了收藏本站喔。
今天给各位分享支持api接口的在线文档的知识,其中也会对提供api接口的平台进行解释,如果能碰巧解决你现在面临的问题,别忘了关注本站,现在开始吧!
本文目录一览:
还在发愁写API文档?推荐一款阿里腾讯都在用的API管理神器
作为一个前后端分离模式开发的团队,我们经常会看到这样的场景:前端开发和后端开发在一起热烈的讨论“支持api接口的在线文档你这接口参数怎么又变支持api接口的在线文档了支持api接口的在线文档?”,“接口怎么又不通了?”,“稍等,我调试下”,“你再试试..."。
那能不能写好接口文档,大家都按文档来开发?很难,因为写文档、维护文档比较麻烦,而且费时,还会经常出现 API 更新了,但文档还是旧的,各种同步不一致的情况,从而耽搁彼此的时间。
之前我们团队也遇到了同样的问题,那么作为研发团队的负责人,我是如何带领团队解决这个问题的呢?
方法其实很简单,如果能做到让写文档/维护文档这件事情的短期收益就能远高于付出的成本,那么所有问题都能迎刃而解,开发人员就会非常乐意去写接口文档。
要做到写文档和及时维护文档的短期收益就能远高于付出的成本,无非两个方向:
鉴于此,我们设想如果有一款工具做到以下这些是不是就非常爽了?
总结下来,我们需要的就是这么一款工具:
为此,我们几乎尝遍了市面上所有相关的工具,但是很遗憾,没有找到合适的。
于是,我们自己实现了一个Postman + Swagger + RAP + JMeter
这个工具就是 Apifox,经常很长一段时间不断更新迭代后,我们基本上完全实现了最初的设想,几乎完美解决了最开始遇到的所有问题,在公司内部大受欢迎。并且也形成了我们自己的最佳实践。
没错,现在我们已经将Apifox产品化对外服务了,你们团队也可以直接使用Apifox了。
官网:www.apifox.cn
Apifox = Postman + Swagger + Mock + JMeter
Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。
通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确支持api接口的在线文档!
节省研发团队的每一分钟!
如果你认为 Apifox 只做了数据打通,来提升研发团队的效率,那就错了。Apifox 还做了非常多的创新,来提升开发人员的效率。
通常一个接口会有多种情况用例,比如 正确用例 参数错误用例 数据为空用例 不同数据状态用例。定义接口的时候定义好这些不同状态的用例,接口调试的时候直接运行,非常高效。
可以独立定义数据模型,接口定义时可以直接引用数据模型,数据模型之间也可以相互引用。同样的数据结构,只需要定义一次即可多处使用;修改的时候只需要修改一处,多处实时更新,避免不一致。
使用 Apifox 调试接口的时候,系统会根据接口文档里的定义,自动校验返回的数据结构是否正确,无需通过肉眼识别,也无需手动写断言脚本检测,非常高效!
Apifox 自动校验数据结构
设置断言:
Apifox 设置断言
运行后,查看断言结果:
先放一张图对比下 Apifox 和其支持api接口的在线文档他同类工具 零配置 mock 出来的数据效果:
Apifox Mock 数据结果对比同类工具
可以看出 Apifox 零配置 Mock 出来的数据和真实情况是非常接近的,前端开发可以直接使用,而无需再手动写 mock 规则。
「Apifox 如何做到高效率、零配置生成非常人性化的 mock 数据」
Apifox 项目可“在线分享” API 文档,分享出去的 API 文档可设置为公开或需要密码访问,非常方便与外部团队协作。
体验地址:https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285
根据接口模型定义,自动生成各种语言/框架(如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等)的业务代码(如 Model、Controller、单元测试代码等)和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。
更重要的是:你可以通过自定义代码模板来生成符合自己团队的架构规范的代码,满足各种个性化的需求。
接口调试
Apifox 多种主题色可选
如何使 WebAPI 自动生成漂亮又实用在线API文档
1.1 SwaggerUI
SwaggerUI 是一个简单
支持api接口的在线文档的Restful API 测试和文档工具。简单、漂亮、易用(官方demo)。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。
2.快速开始
创建项目 OnlineAPI来封装百度音乐服务(示例下载)
支持api接口的在线文档,通过API可以搜索、获取音乐的信息和播放连接。
我尽量删除一些我们demo中不会用到的一些文件
支持api接口的在线文档,使其看上去比较简洁。
WebAPI 安装 Swashbuckle
Install-Package Swashbuckle
代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的,生成 SwaggerUI,JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件,用于配置 SwaggerUI 相关展示行为的。如图:
将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在当前类中添加一个方法
/// <summary
/// </summary
/// <param name="name"</param
/// <returns</returns
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}
紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”,编译过程中生成类库的注释文件
添加百度音乐 3个API
访问 lt;youhost/swagger/ui/index,最终显示效果
我们通过API 测试API 是否成功运行
3.添加自定义HTTP Header
在开发移动端 API时常常需要验证权限,验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可
首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
public class HttpHeaderFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry
schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null) operation.parameters = new
List<Parameter();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判断是否添加权限过滤器
var isAuthorized = filterPipeline.Select(filterInfo =
filterInfo.Instance).Any(filter = filter is IAuthorizationFilter);
//判断是否允许匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute().Any();
if (isAuthorized !allowAnonymous)
{
operation.parameters.Add(new Parameter
{
name = "access-key",
@in = "header",
description = "用户访问Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter();
添加Web权限过滤器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class AccessKeyAttribute : AuthorizeAttribute
{
/// <summary
/// 权限验证
/// </summary
/// <param name="actionContext"</param
/// <returns</returns
protected override bool IsAuthorized(HttpActionContext actionContext)
{
var request = actionContext.Request;
if (request.Headers.Contains("access-key"))
{
var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 验证Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 处理未授权的请求
/// </summary
/// <param name="actionContext"</param
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
{
var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
actionContext.Response = new HttpResponseMessage
{
Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
};
}
}
}
在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]
最终显示效果
4.显示上传文件参数
SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似,只是我们通过特殊的设置来标示API具有上传文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class UploadFilter : IOperationFilter
{
/// <summary
/// 文件上传
/// </summary
/// <param name="operation"</param
/// <param name="schemaRegistry"</param
/// <param name="apiDescription"</param
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (!string.IsNullOrWhiteSpace(operation.summary) operation.summary.Contains("upload"))
{
operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter
{
name = "file",
@in = "formData",
required = true,
type = "file"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter();
API 文档展示效果
在定制开发程序中接入腾讯文档
腾讯文档是腾讯于2018年4月推出的一款可多人在线协作的免费文档产品。目前支持在线文档、表格、收集表、PPT、PDF、思维导图、流程图七种文档品类,同时为合作伙伴提供丰富的API接口,只需轻量级开发即可接入自身产品,补齐文档解析、在线编辑、长内容储存、远程演示、内容读取、信息收集等能力。
针对文档功能,提供完善的编辑能力,轻松设置文字样式和段落格式,添加图片、链接和表格等,可快速导入导出word文档,便捷追溯 历史 版本,随时随地与他人协作,轻松制作生动的文档。
针对表格功能,支持多人同时处理同一份表格,可一键转为收集表格,高效收集信息和数据,提供数据验证、条件格式、筛选排序、200多种函数及常用图表等多种专业功能,随时随地处理数据。
针对幻灯片功能,支持常用的形状和动画,可导入本地PPT,随时随地协作编辑,高效汇总文档,分享链接即可邀请好友在线远程演示,手机端、电脑端均可查看。
提供的在线表格收集功能,一张收集表可收集百万份信息,结果实时汇总到在线表格,数据实时分析;提供单选、多选、图片、温度、位置等丰富问题类型,支持数据校验,高效收集信息。
同时腾讯文档也提供了思维导图的功能,提供基础图、树状图、组织结构图等多种图形结构,可插入图片、链接、备注、图标等丰富内容,支持导入XMind文档;可多人在线协作,云端存储,多设备同步;轻松构思,让你有序整理和标记思路。
用户只需在官网按指引填写注册信息,并完成对公账号打款验证即可接入腾讯文档开放平台API。腾讯文档开放平台持续迭代更新,现阶段暂时面向企业主体用户开放API接入,详细流程可查看:腾讯文档开放平台企业主体注册流程。企业主体用户按指引填写注册信息时,需要上传工商营业执照,系统会在3个工作日内完成工商信息审核。工商信息审核通过后,企业主体用户需要填写对公账号信息,提交后系统会向对公账号打一笔1元以下的资金,对公账号会在2个工作日内收到这笔资金,只需回写正确的金额即可认证成功,开始使用开腾讯文档放平台能力。企业全程无需支付任何费用。
目前腾讯文档支持API接入和小程序接入。腾讯文档开放平台开发文档网址如下:
https://docs.qq.com/open/wiki/
针对该文档,我们可以采用相关的开发语言进行集成类的开发。例如我们在C#下集成的TencentDocument类库。
YApi~API接口文档
YApi
地址链接: https://yapi.baidu.com/
文档链接: https://yapi.baidu.com/doc/documents/index.html
安装过程就不做复述
支持api接口的在线文档了
支持api接口的在线文档,文档写的非常全
在一个项目的开发过程之中,我相信基本上所有的开发人员都需要用到接口模拟请求的工具,例如POSTMAN啊
java的注解生成文档工具swagger啊
但是在实际开发过程中,前后端人员可能需要提前确定文档地址以及格式、参数等信息,
postman作为一个模拟请求的工具起不到记录功能
swagger只能通过注解、实体类、参数等信息生成文档,无法提前记录
这个时候就要提到Yapi中的运行这个功能了,只要安装一个chrome插件,马上实现在线调试功能
同时可以在设置中去配置一下环境设置,这样在开发过程中可以通过切换环境访问不同后端开发人员的本地开发环境,方便多人多模块同时调试
赤狐博客地址: https://blog.51chihu.com
神器 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("https://github.com/macrozheng/mall-learning"))) .externalDocs(newExternalDocumentation() .description("SpringBoot实战电商项目mall(50K+Star)全套文档") .url("http://www.macrozheng.com")); }@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("https://github.com/macrozheng/mall-learning"))) .externalDocs(newExternalDocumentation() .description("SpringBoot实战电商项目mall(50K+Star)全套文档") .url("http://www.macrozheng.com")) .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界面了,访问地址:http://localhost:8088/swagger-ui.html
我们先通过登录接口进行登录,可以发现这个版本的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有点卡手的朋友可以迁移到它试试!
参考资料
项目地址:https://github.com/springdoc/springdoc-openapi
官方文档:https://springdoc.org/
项目源码地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc
https://mp.weixin.qq.com/s/scityFhZp9BOJorZSdCG0w
谁用过比较好用点的文档识别API接口,可以支持多种语言开发的,有吗?求推荐
比如云脉文档识别API接口,使用ocr功能,可将图片上的文字进行识别,而且API开发支持Java、C++、C、 object pascal及objective-C等多种语言,在云脉OCR开发者平台注册并登录账号即可自主下载...
关于支持api接口的在线文档和提供api接口的平台的介绍到此就结束了,不知道你从中找到你需要的信息了吗 ?如果你还想了解更多这方面的信息,记得收藏关注本站。
支持api接口的在线文档的介绍就聊到这里吧,感谢你花时间阅读本站内容,更多关于提供api接口的平台、支持api接口的在线文档的信息别忘了在本站进行查找喔。
版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。
暂时没有评论,来抢沙发吧~