- 使用 Spring Initializr 创建 Spring Boot 应用程序
- 在Spring Boot中配置Cassandra
- 在 Spring Boot 上配置 Tomcat 连接池
- 将Camel消息路由到嵌入WildFly的Artemis上
什么接口文档都不用手写了?自动挡?
我们知道前后端分离,前端一般按后端写好的接口去开发,那么就需要我们明细后端接口数据等,需要写接口文档,前端按照接口文档去开发
1. EOLINKER(推荐)可以协作,界面简洁
地址:https://www.eolinker.com/#/?status=link-jump
2.RAP(前阿里妈妈团队)支持版本管理,开源,有文档
地址:http://rap2.taobao.org/
3.EasyAPI (相对来说easy)
地址:https://www.easyapi.com/
4.apizza
地址:https://apizza.net/pro/#/
5.showdoc
地址:https://www.showdoc.cc/
6.胖胖羊
地址:http://doclever.cn/controller/console/console.html
REST framewrok生成接口文档需要coreapi
库的支持。
安装:pip install coreapi
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls
参数title
为接口文档网站的标题
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('docs/', include_docs_urls(title='站点页面标题'))
]
1) 单一方法的视图,可直接使用类视图的文档字符串,如
class BookListView(generics.ListAPIView):
"""
返回所有图书信息.
"""
2)包含多个方法的视图,在类视图的文档字符串中,分开方法定义,如
class BookListCreateView(generics.ListCreateAPIView):
"""
get:
返回所有图书信息.
post:
新建图书.
"""
3)对于视图集ViewSet,仍在类视图的文档字符串中分开定义,但是应使用action名称区分,如
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
"""
list:
返回图书列表数据
retrieve:
返回图书详情数据
latest:
返回最新的图书数据
read:
修改图书的阅读量
"""
写视图类,只需要加注释即可
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
# 新版drf schema_class默认用的是rest_framework.schemas.openapi.AutoSchema
}
# 不配置报错:#AttributeError: 'AutoSchema' object has no attribute 'get_link'
浏览器访问 127.0.0.1:8000/docs/,即可看到自动生成的接口文档。
1) 视图集ViewSet中的retrieve名称,在接口文档网站中叫做read
2)参数的Description需要在模型类或序列化器类的字段中以help_text选项定义,如:
class Student(models.Model):
...
age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
...
或
class StudentSerializer(serializers.ModelSerializer):
class Meta:
model = Student
fields = "__all__"
extra_kwargs = {
'age': {
'required': True,
'help_text': '年龄'
}
}
一般来说,headers里的信息都是通用的,可以提前说明,作为默认参数
URL中参数表达式使用mustache的形式,参数包裹在双大括号之中``
例如:
/api/user/
/api/user/?age=&gender=
数据模型定义包括:
数据模型的最小数据集:
一些文档里可能会加入字段的类型,但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化,大部分数据类型都是字符串。一些特殊的类型,例如枚举类型的字符串,可以在说明里描述。
另外:数据模型非常建议使用表格来表现
。
举个栗子?:
名称 | 是否必须 | 说明 |
---|---|---|
userType | 是 | 用户类型。commom 表示普通用户,vip 表示vip用户 |
age | 否 | 用户年龄 |
gender | 否 | 用户性别。1 表示男,0 表示女 |
// general
POST http://www.testapi.com/api/user
// request payload
{
"name": "HammerZe",
"age": 18,
"like": ["music", "reading"],
"userType": "vip"
}
// response
{
"id": "asdkfjalsdkf"
}
异常处理最小数据集
举个栗子?:
状态码 | 说明 | 解决方案 |
---|---|---|
401 | 用户名密码错误 | 检查用户名密码是否正确 |
424 | 超过最大在线数量 | 请在控制台修改最大在线数量 |
之前我一直不想把解决方案加入异常处理的最小数据集,但是对于很多开发者来说,即使它知道424
代表超过最大在线数量
。如果你不告诉如果解决这个问题,那么他们可能就会直接来问你。所以最好能够一步到位,直接告诉他应该如何解决,这样省时省力。
1 请求示例
// general
POST http://www.testapi.com/api/user/vip/?token=abcdefg
// request payload
{
"name": "qianxun",
"age": 14,
"like": ["music", "reading"]
}
// response
{
"id": "asdkfjalsdkf"
}
2 路径与查询字符串参数模型POST http://www.testapi.com/api/user//?token=
名称 | 是否必须 | 说明 |
---|---|---|
userType | 是 | 用户类型。commom 表示普通用户,vip 表示vip用户 |
token | 是 | 认证令牌 |
3 请求体参数模型
名称 | 是否必须 | 说明 |
---|---|---|
name | 是 | 用户名。4-50个字符 |
age | 否 | 年龄 |
like | 否 | 爱好。最多20个 |
4 响应体参数模型
名称 | 说明 |
---|---|
id | 用户id |
5 异常处理
状态码 | 说明 | 解决方案 |
---|---|---|
401 | token过期 | 请重新申请token |
424 | 超过最大在创建人数 | 请在控制台修改最大创建人数 |
请求示例
: 请求示例放在第一位的原因是,要用最快的方式
告诉开发者,这个接口应该如何请求路径与查询字符串参数模型
: 使用mustache
包裹参数请求体参数模型
:如果没有请求体,可以不写响应体参数模型
异常处理
文档建议由一下两种形式,在线文档
,pdf文档
。
在线文档
更新方便
易于随时阅读
易于查找
PDF文档
内容表现始终如一,不依赖文档阅读器
文档只读,不会被轻易修改
其中由于是面对第三方开发者,公开的在线文档必须提供
;由于某些特殊的原因,可能需要提供文件形式的文档,建议提供pdf文档。当然,以下的文档形式是非常不建议
提供的:
word文档和markdown文档有以下缺点:
文档的表现形式非常依赖文档查看器
:各个版本的word文档对word的表现形式差异很大,可能在你的电脑上内容表现很好的文档,到别人的电脑上就会一团乱麻;另外markdown文件也是如此。而且markdown中引入文件只能依靠图片链接,如果文档中含有图片,很可能会出现图片丢失的情况。文档无法只读
:文档无法只读,就有可能会被第三方开发者在不经意间修改,那么文档就无法保证其准确性了。总结一下,文档形式的要点:
只读性
:保证文档不会被开发者轻易修改一致性
:保证文档在不同设备,不同文档查看器上内容表现始终如一易于版本管理
:文档即软件(DAAS: Document as a Software),一般意义上说软件 = 数据 + 算法
, 但是我认为文档也是一种组成软件的重要形式
。既然软件需要版本管理,文档的版本管理也是比不可少的。我想做的是,如果鼠标位于“下一个”按钮上,它会以慢速向右滚动,如果鼠标没有位于“下一个”按钮上,它会停止滚动? 这是我的尝试http://jsfiddle.net/mdanz/nCCRy/14/ $(
StyleCop 是一个很棒的视觉工作室小插件。但它不会向您显示实时提示或提供任何自动修复。 随之而来的是 reSharper 和 StyleCop for reSharper,这是理想的解决方案,但
我为我的MatchQuery使用了模糊性选项,但是我想将模糊性值设置为auto。有什么办法吗? 另外,对于完成建议程序,您可以将其设置为支持unicode,对于我的MatchQuery,有什么方法可以
我想从表中获取一行[字符串名称,字符串密码,int 某些内容]并将其映射到一个 User 对象,该对象具有 3 个属性,如上面的 getter 和 setter有什么方法可以自动完成吗?我考虑过反射,
我有一个像这样的方法:void m1(string str) 并且有一个像这样的类: public class MyClass { public bool b1 { set; get; }
我正在尝试使用 $rootScope 从一个 Controller 向另一个 Controller $broadcast 一些数据。 如果我使用像 ng-click 这样的触发器来运行将广播的功能,它
我考虑了很多关于是要使用完全自动化的缓存还是手动缓存。 我们的自动方法是一种解决方案,它可以挖掘数据库、查询和格式化每个潜在和 future 的数据请求,并将其保存到适当的缓存存储(内存缓存或基于磁盘
我的 CSS 必须使用过渡来更改,直到现在我都使用 div:hover 来实现。 当您单击另一个 div 时需要激活过渡,而不是当您将鼠标悬停在必须移动/更改的 div 上时。 我该怎么做? 谢谢 永
在我的应用程序中,我需要一些动画,但如果它已经设置了动画,则不需要持续时间。但我的问题是它会自动添加持续时间。 在这里你可以看到 2 个函数,第二个没有持续时间但它确实有持续时间(可能从 1 秒开始)
两年前,我需要制作一个工具,通过 POST 自动将 txt/csv 文件上传到我的 Web 服务器,然后使用 cronjob 通过 PHP 对其进行解析。 这有两次在每天午夜自动发生。尽管这行得通,但
请阅读下面程序中的评论: #include void test(char c[]) { c=c+2; //why does this work ? c--; printf("%
也许是个幼稚的问题,但是...... 确认或拒绝: 自动和静态存储持续时间的对象/变量的内存的存在是在编译时确定的,程序运行时失败的可能性绝对为零,因为没有足够的内存用于自动对象。 自然地,当自动对象
有没有什么方法可以自动获得类中属性更改的通知,而不必在每个 setter 中都编写 OnPropertyChanged? (我有数百个属性,我想知道它们是否已更改)。 安东建议 dynamic pro
我们在使用 Azure DevOps 的项目中采用了 gitflow 流程。我有以下场景: 当功能分支合并到 Develop 时,我想在完成拉取请求的同时执行压缩合并策略 当 Release 分支定期
我的网站上有一个评论部分,我将 html 编码的评论保存在我的数据库中。所以我添加了这条评论- "testing" `quotes` \and backslashes\ and html 并将其保存在
是否存在“ checkin 前 TFS 自动 checkout ”这样的功能,以便在我说“ checkin ”之前我不会 checkout 任何文件,例如以防我只是临时更改文件 - 这一直发生。 换句
我有一个运行在 Linux/Apache/Tomcat 堆栈上的网站,它需要每隔几个月自动脱机以进行服务器维护,这将持续任意时间。有哪些选项可以让 Apache 建立和取消“服务器维护”页面? 我需要
我经常在工作中创建文档,在公司内部,由于我们使用的首字母缩写词和缩写词的数量,我们几乎拥有自己的语言。因此,我厌倦了在发布文档之前手动创建首字母缩写词和缩写表,并且快速的谷歌搜索发现了一个可以有效地为
我希望在用户或宏将计算模式从自动更改为手动或手动更改为自动时运行代码。是否有为此触发的事件? (属性是 Application.Calculation 在 Excel 互操作中。) 使用 Excel
这个问题在这里已经有了答案: Repeat command automatically in Linux (13 个回答) 6年前关闭。 我想创建一个脚本来获取另一个文件夹中的所有文件夹名称。并为这些
我是一名优秀的程序员,十分优秀!