发表于: 2019-12-30 13:14:57

1 1180


今天完成的事情:

1.学习关于接口文档的相关知识

2.编写接口文档

1)新增学生信息

请求地址:

post /a/u/student

请求参数:

字段

说明

类型

是否必填

name

姓名

String

qq

qq

Number

job

修真类型

String

arriveTime

预计入学时间

Number

school

院校

String

studentId

学号

Number

link

日报链接

String

wish

立愿

String

knownWays

了解方式

String

bro

师兄

String

返回参数:

字段

说明

类型

是否必填

code

响应码

Number

massage

返回信息

String


2)删除学生信息

请求地址:

delete /a/u/student/{id}

请求参数:

字段

说明

类型

是否必填

id

用户id

Number

返回参数:

字段

说明

类型

是否必填

code

响应码

Number

massage

返回信息

String


3)修改学生信息

请求地址:

put /a/u/student/{id}

请求参数:

字段

说明

类型

是否必填

id

用户id

Number

返回参数:

字段

说明

类型

是否必填

code

响应码

Number

massage

返回信息

String


4)查询学生信息

请求地址:

get /a/u/student/search

请求参数:

字段

说明

类型

是否必填

id

用户id

Number

返回参数:

字段

说明

类型

是否必填

code

响应码

Number

massage

返回信息

String

data

返回体

Object

data:

字段

说明

类型

是否必填

name

姓名

String

qq

qq

Number

job

修真类型

String

arriveTime

预计入学时间

Number

school

院校

String

studentId

学号

Number

link

日报链接

String

wish

立愿

String

knownWays

了解方式

String

bro

师兄

String


3.学习SpringMVC


明天计划的事情:

继续学习SpringMVC


遇到的问题: 

找了挺多例子,helloworld也没弄出来,明天接着找吧,看那任务步骤又蒙了,看不懂,就先学学SpringMVC吧,接口文档也不知道写的对不对。


收获:

一、什么是接口文档?

在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。


二、为什么要写接口文档?

1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发。

2、项目维护中或者项目人员更迭,方便后期人员查看、维护。


三、接口规范是什么?
首先接口分为四部分:方法、uri、请求参数、返回参数
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
2、uri:以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了。
3、请求参数和返回参数,都分为5列:字段、说明、类型、备注、是否必填
字段是类的属性;说明是中文释义;类型是属性类型,只有String、Number、Object、Array四种类型;备注是一些解释,或者可以写一下例子,比如负责json结构的情况,最好写上例子,好让前端能更好理解;是否必填是字段的是否必填。
4、返回参数结构有几种情况:1、如果只返回接口调用成功还是失败(如新增、删除、修改等),则只有一个结构体:code和message两个参数;2、如果要返回某些参数,则有两个结构体:1是code/mesage/data,2是data里写返回的参数,data是object类型;3、如果要返回列表,那么有三个结构体,1是code/mesage/data,data是object,里面放置page/size/total/totalPage/list 5个参数,其中list是Arrary类型,list里放object,object里是具体的参数。


四、文档至少包含以下信息

1.接口功能
2.接口路径
3.接口入参
4.接口出参
5.各字段说明、约定值、是否必填、默认参数
6.复杂数据结构给出出范例


五、URI

<1>什么是URI

URI,通一资源标志符(Uniform Resource Identifier, URI),表示的是web上每一种可用的资源,如 HTML文档、图像、视频片段、程序等都由一个URI进行定位的。

<2>URI的结构组成

URI通常由三部分组成:

①访问资源的命名机制;

②存放资源的主机名;

③资源自身的名称。

<3>URI举例

如:https://blog.csdn.net/qq_32595453/article/details/79516787

我们可以这样解释它:

①这是一个可以通过https协议访问的资源,

②位于主机 blog.csdn.net上,

③通过“/qq_32595453/article/details/79516787”可以对该资源进行唯一标识(注意,这个不一定是完整的路径)

注意:以上三点只不过是对实例的解释,以上三点并不是URI的必要条件,URI只是一种概念,怎样实现无所谓,只要它唯一标识一个资源就可以了。


六、URL

URL是URI的一个子集。它是Uniform Resource Locator的缩写,译为“统一资源定位 符”。

通俗地说,URL是Internet上描述信息资源的字符串,主要用在各种WWW客户程序和服务器程序上。

采用URL可以用一种统一的格式来描述各种信息资源,包括文件、服务器的地址和目录等。URL是URI概念的一种实现方式。

URL的一般格式为(带方括号[]的为可选项):

protocol :// hostname[:port] / path / [;parameters][?query]#fragment

URL的格式由三部分组成: 

①第一部分是协议(或称为服务方式)。

②第二部分是存有该资源的主机IP地址(有时也包括端口号)。

③第三部分是主机资源的具体地址,如目录和文件名等。

第一部分和第二部分用“://”符号隔开,

第二部分和第三部分用“/”符号隔开。

第一部分和第二部分是不可缺少的,第三部分有时可以省略。 


七、URL和URI的区别

URL是一种具体的URI,它是URI的一个子集,它不仅唯一标识资源,而且还提供了定位该资源的信息。URI 是一种语义上的抽象概念,可以是绝对的,也可以是相对的,而URL则必须提供足够的信息来定位,是绝对的。


八、SpringMVC概述:

1,它是SpringWebMVC的简称,SpringMVC就是Spring框架提供的一个模块,目的是要简化日常的Web开发。

2,SpringMVC框架的核心组件
        1.DispatcherServlet: 前端控制器,用来过滤客户端发送过来,想要进行逻辑处理的请求。
        2.Controller/Headler: 控制器/处理器。
        3.HandlerMapping: 处理器映射器。
        4.HandlerAdaptor:处理器适配器。
        5.ViewResolver:视图解析器。



返回列表 返回列表
评论

    分享到