我们后端在编写项目的时候,往往都会在代码上加上注释,方便自己以后的修改和维护,和方便别人的理解。但是对对前后端分离的项目,前端人员写前端代码,后端人员编写后端的代码。这样的话当前端需要调用我们后端的接口的时候,就会来找我们询问参数以及请求的接口路径。如果每次都来问的话就会很繁琐。所以我们要讲我们自己编写的代码,生成一个api文档,里面描述了我们各种接口调用规则,我们只需要将这个api文档交给前端人员即可。前端人员就可以根据我们提供的文档获取到他们需要调用的接口路径以及参数信息。
使用 swagger2 可以帮助我们自动的生成一个api接口文档,我们只需要在编写代码的时候,加上一些注解,注解里面的参数写上我们对接口以及参数的解释和使用规则即可。
使用swagger2
首先要将 swagger2 的依赖引入,我们在引入依赖的同时,可以将 swagger2 的ui也同时引入,这样生成的api界面会看上去更加舒适。
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.1.RELEASE</version>
</dependency>
<!--好看的ui-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
引入之后要创建一个 swagger2 的配置类,我们需要将那个微服务上的接口生成api帮助文档,就可以将配置类创建在哪个微服务中,在创建的类上,必须加入注解 @Configuration
@EnableSwagger2
/**
* @program: springcloud02
* @description: Swagger的配置类
* @author: mitu_echo
* @create: 2021-07-10 14:45
**/
package com.hyn.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* swagger的功能都封装再Docket类中 必须创建一个Docket类
*/
@Bean
public Docket docket(){
Docket docket=new Docket(DocumentationType.SWAGGER_2)
// swagger接口信息
.apiInfo(getApiInfo())
// 为那些接口生成文档
.select()
.apis(RequestHandlerSelectors.basePackage("com.hyn.controller"))
// 指定那些路径生成接口文档
// .paths(RequestHandlerSelectors.)
.build();
return docket;
}
/**
* 创建 apiinfo 对象
* @return
*/
private ApiInfo getApiInfo(){
/**
* name 是作者名
* url 是作者的网站
* email 是作者的邮箱
* title 是api文件页面显示的标题
* version 是版本号
* termOfServiceUrl 是团队/公司的网站
*/
Contact DEFAULT_CONTACT = new Contact("mitu_echo", "https://blog.csdn.net/qq_15513905?spm=1001.2101.3001.5343", "1263628616@qq.com");
ApiInfo apiInfo = new ApiInfo("mitu_echo的Api接口文档", "mitu_echo的Api接口文档", "8888", "https://blog.csdn.net/qq_15513905?spm=1001.2101.3001.5343",
DEFAULT_CONTACT, "迷途公司", "https://blog.csdn.net/qq_15513905?spm=1001.2101.3001.5343", new ArrayList<VendorExtension>());
return apiInfo;
}
}
在浏览器使用 ip地址+微服务端口号+/doc.html进行 aip接口页面的访问