毕设利器，教你从零搭建一个有规范的spring boot项目【六】——接口文档和RESTful API

最新推荐文章于 2024-06-04 09:21:15 发布

TandK

最新推荐文章于 2024-06-04 09:21:15 发布

阅读量276

点赞数

分类专栏： SpringBoot 文章标签： spring restful spring boot

本文链接：https://blog.csdn.net/qq_41180335/article/details/120616688

版权

SpringBoot 专栏收录该内容

10 篇文章 2 订阅

订阅专栏

接上篇《毕设利器，教你从零搭建一个有规范的spring boot项目【五】——用户身份信息验证》

接口文档

接口文档大部分时候是写给前端同学看的，需要你写明这个接口是干嘛的、传什么参数、返回什么数据。

不然前后端分离的项目里，如果不是自己一个人做，前端同学就会一个一个接口地拿过来问你，问到你崩溃。

前阵子接手了公司的一个项目，才发现接口文档原来也是给后面接手项目的后端同学看的。

你想想，刚接手一个项目，什么都没跟你说，就要你维护这个项目，你🐎的，没有接口文档，都不能大致了解这个项目。

所以，写好接口文档这个事，至少在公司里，是一个很重要很重要的事。

有一个叫swagger的工具，能够帮助我们很好地撰写接口文档，实时更新文档，好处我就不多说了，如果你真有写接口文档的需求，用过其他工具，再回头看swagger，你就会慢慢发现swagger的好处了。

这里就直接说怎么用吧。

首先引入swagger的依赖：

<!-- Swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<!-- 文档 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
	<exclusions>
		<exclusion>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-models</artifactId>
		</exclusion>
		<exclusion>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<!--https://mvnrepository.com/artifact/io.swagger/swagger-models -->
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-models</artifactId>
	<version>1.5.21</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.8.5</version>
</dependency>
<!--swagger-->

配置一下swagger，在core包下新建一个swagger包，编写SwaggerConfig类配置swagger：

在这里插入图片描述
我将我的配置代码粘出来，不同的项目肯定配置不一样的，所以最好根据你的情况改一下配置，粘完代码后会仔细说明的：

package com.TandK.core.swagger;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

@Profile("!pro")
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {


    @Bean
    public Docket createAPI() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("Authrization").description("Authrization安全验证")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .defaultValue("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJUYW5kSyIsInVzZXJVdWlkIjoiMTQyOTA1MjA5MDQzODI5OTY1MCIsImlhdCI6MTYyOTU0NzU0MywianRpIjoiZTEzNDRiZTktZTg5ZS00YWY2LThlM2ItMjkwZTNmNjNmZWNhIn0.iKTVAZYGK0IavBcjjSVahUPGvvmoWxdDB9Dh0sqncjA")
                .required(false).build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_12)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.TandK.controller"))
                //过滤生成链接
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .useDefaultResponseMessages(false)
                .securitySchemes(Collections.singletonList(apiKey()))
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("TandK", "", "1098446876@qq.com");
        return new ApiInfoBuilder().title("turntable🧒")
                .description("服务端接口文档")
                .contact(contact)
                .version("1.0.0")
                .build();
    }

    @Bean
    public SecurityScheme apiKey() {
        return new ApiKey("Authrization", "Authrization", "header");
    }


}

类的注解说明：
在这里插入图片描述
联系人信息：

大多数接口都需要同一个参数，比如token，很多接口都需要带在请求头上，我们也可以配置一下，这样前端同学调试的时候可以省很多功夫。

比如我在这里配置了请求头带上token：
在这里插入图片描述

启动项目，就可以访问了接口文档了。

有两个访问地址，都介绍一下，你自己挑一个看就行，很多时候我们写完接口了，也需要自己调试的，这个时候用swagger就行了。

第一个：

{{URI}}/swagger-ui.html#/

我是本地启动项目的，因此我直接访问http://localhost:8080/swagger-ui.html#/就可以了。

图示如下：
在这里插入图片描述

在这里插入图片描述

第二个：

{{URI}}/doc.html

同样的，本地访问http://localhost:8080/doc.html即可，调试功能基本一致，但是页面大不相同，这里不再解释一个个按钮在哪了，只介绍上面那个页面所没有的一些功能：

在这里插入图片描述
这个搜索功能还是很强大的，值得特意介绍，特别是当项目大起来了，接口越来越多的时候。

页面大概的介绍就是这些，剩下的，只要你需要用到，用着用着都会熟悉的。

这样接口就做好了吗？

不是的，这只是个开始而已，你仔细看一下接口文档：
在这里插入图片描述

看看这个接口的文档，都是英文，这个接口还算简单，真要复杂起来，你指望人家看见你一个addUser就知道这个接口是干嘛的吗？

所以说接口文档的撰写现在才开始，之前只是做了一些简单的配置而已。

不过既然是工具咯，肯定是为了让编写接口文档这件事变得越简单越好，其实一个接口搞下来，大概就只需要用到3-4个注解，就可以把一个接口写的清清楚楚。

第一个：@Api(tags = "")

看图，可以清楚地看到，这个注解是写在类上的，用来描述这个Controller类是用来干嘛的。
在这里插入图片描述
写完之后重新启动项目，刷新一些swagger的页面，可以看到，只有这个controller的名称发生了改变，index-controller没写注解，就还是英文：

这样子，前端同学就知道关于用户的接口都可以在这里找。

第二个：@ApiOperation(value = "", response = XXX.class)

在这里插入图片描述

这里的返回类型，如果是我们自定义的类，比如上面的UserVO，我们还可以用第三个注解@ApiModelProperty("")说明里面的字段，比如：

在这里插入图片描述
你在UserVO写好对应的注解后，可以发现UserVO不论是作为返回类型，还是参数都会有对应的描述。

重启项目再刷新swagger页面：

在这里插入图片描述

如果你有的接口不需要太多参数，简简单单的get，就带一两个参数，比如一个分页的查询，只需要前端传页数和页码，接口写起来这样子：

在这里插入图片描述

那该怎么写好对他们的描述呢？

这个时候可以用到第四个注解：@ApiImplicitParams和@ApiImplicitParam。

多个参数的时候用@ApiImplicitParams，里面包着多个@ApiImplicitParam，如图：
在这里插入图片描述

单个参数的时候用@ApiImplicitParam就可以了：

在这里插入图片描述

这样，一个接口用这4个注解，就可以很简单生成一个实时更新的文档了，你想改文档说明？直接改注解里的值就可以了。

RESTful API

写好接口文档是一件很重要的事，写好接口本身则更重要，如果说swagger是你写好接口文档的一个好工具的话，RESTful API则是为你写好接口提供了好规范。

规范之所以叫规范，就是你不遵守也可以，但为什么还要遵守呢？

大家一起合作一个项目，没有一个统一的规范，是需要花费不少时间来沟通的，而这些沟通的时间，是你遵守好规范，就可以节约起来的。

你不想下班的时候，回到家里了，还在加班的前端跑来抓着你问个没完吧？

这个时候只要你很好地遵守了规范，你就可以理直气壮地让他好好看文档，好好看完，有不懂的再来问。

如果你没有呢？那人家就会可能就会说你写的什么鬼东西，反而是我们不对了。

因此遵守好规范，我个人觉得是个很重要的事，特别是接口的规范，什么时候用get、什么时候用post、put和delete又是什么时候用，接口的url又该怎么用。

如果你不知道的话，了解一下规范并跟着用一段时间，我相信也会在各个方面增加你的见识。

哪怕你用完了之后，破口大骂，这是什么鬼东西，老子不用了，这也是你用完之后，清楚地认识到了这个东西的缺点，是你实践过后自己独立的见解。

这就是我为什么认为不遵守也可以的规范，我们要去了解并尝试的原因。

关于RESTful API，我之前已写过相应的文章《RESTful API实践总结 | 我们上网，是一个怎样的过程？》

这里不再赘述，如果你觉得写的还可以，不妨点个关注🌹

有什么问题可以留言，看到了都会尽量帮忙解决。

TandK

关注

0
点赞
踩
3

收藏

觉得还不错? 一键收藏
打赏
0
评论
毕设利器，教你从零搭建一个有规范的spring boot项目【六】——接口文档和RESTful API

接上篇《毕设利器，教你从零搭建一个有规范的spring boot项目【五】——用户身份信息验证》接口文档接口文档大部分时候是写给前端同学看的，需要你写明这个接口是干嘛的、传什么参数、返回什么数据。不然前后端分离的项目里，如果不是自己一个人做，前端同学就会一个一个接口地拿过来问你，问到你崩溃。前阵子接手了公司的一个项目，才发现接口文档原来也是给后面接手项目的后端同学看的。你想想，刚接手一个项目，什么都没跟你说，就要你维护这个项目，你????的，没有接口文档，都不能大致了解这个项目。所以，写好接口文
复制链接

扫一扫