第一部分:
我第一次听到这个名字的时候一下子懵了然后对于API的编写以及编写格式都不是很懂,然后看到老师给的两个文档,一个是gitee上的一个产品文档格式大致如下`
request
pageNum(default=1)
pageSize(default=10)
response
success
{
“status”: 0,
“data”: {
“pageNum”: 1,
“pageSize”: 10,
“size”: 2,
“orderBy”: null,
“startRow”: 1,
“endRow”: 2,
“total”: 2,
“pages”: 1,
“list”: [
{
“id”: 1,
“categoryId”: 3,
“name”: “iphone7”,
“subtitle”: “双十一促销”,
“mainImage”: “mainimage.jpg”,
“status”:1,
“price”: 7199.22
},
{
“id”: 2,
“categoryId”: 2,
“name”: “oppo R8”,
“subtitle”: “oppo促销进行中”,
“mainImage”: “mainimage.jpg”,
“status”:1,
“price”: 2999.11
}
],
“firstPage”: 1,
“prePage”: 0,
“nextPage”: 0,
“lastPage”: 1,
“isFirstPage”: true,
“isLastPage”: true,
“hasPreviousPage”: false,
“hasNextPage”: false,
“navigatePages”: 8,
“navigatepageNums”: [
1
]
}
}
fail
{
“status”: 10,
“msg”: “用户未登录,请登录”
}
当时看这一段也不是很明白,只是自己觉得这应该是说在接口上的正确返回值和错误返回值。以及相关的提示信息
第二部分:
老师让参考swagger来写API设计文档,我的理解是这应该是一个工具吧,然后看看这使用指南,这个工具确实好用,可以生成、描述、调用和可视化RESTful风格的Web服务。然后我就看看怎么用;首先呢,第一步根据文档指南说先引入一个依赖,如下图`
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
链接:https://www.jianshu.com/p/f4fb5e9899fc第二步Springboot整合swagger代码如下:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket productApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //添加ApiOperiation注解的被扫描
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档")
.version("1.0").build();
}
}
链接:https://www.jianshu.com/p/f4fb5e9899fc
我就是根据文档然后操作,不过由于自己技术不是很好,遇到了很多问题,最后没有成功生成接口文档。我觉得自己没有真正的了解接口,对于如何区分接口以及接口的目的是什么,没有搞清楚,一就直接导致了自己的实验失败。