-
认真是一种态度,坚持是一种品格,优秀是一种习惯！
随着技术的不断革新，目前大多数互联网公司引进了前后端分离的开发模式。前端负责页面的开发，包括页面样式以及相关接口对接；而后端则专注于后台业务的实现。这样确实极大的提高了开发效率。但同时也带了沟通上的问题，因为接口都是后台实现和提供的。那么就必须写好相应的接口文档，告知前端接口地址、接口参数规范等等。因此我们引入了swagger一个为接口文档而生的开源项目，它以注解的方式，让后端在开发过程中就可以通过简单便捷的方式完成接口文档编写。
效果如下图：
接口文档效果
基础理论
-
swagger常用注解及说明：
@Api():用于类，标识这个类是swagger的资源
@ApiOperation():用于方法,表示一个http请求的操作
@ApiParam():用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）
@ApiModel():用于类 ,表示对类进行说明，用于参数用实体类接收
@ApiModelProperty():用于方法，字段 ,表示对model属性的说明或者数据操作更改
@ApiIgnore():用于类，方法，方法参数 ,表示这个方法或者类被忽略
@ApiImplicitParam(): 用于方法 ,表示单独的请求参数
@ApiImplicitParams(): 用于方法，包含多个@ApiImplicitParam
Tips:
若参数实体类某个参数不想显示到接口文档中，可通过ApiModelProperty实现，实现方式：
@ApiModelProperty(hidden=true)
- 那么我们现在就简单说说
Springboot项目中如何整合进swagger2.
项目框架：
JDK 1.8
SpringBoot 2.1.5.RELEASE
Swagger 2.9.2
swagger-bootstrap-ui 1.9.4
创建项目
在坚持学习第一天中已经讲过SpringBoot项目的创建了，此处不再赘述。可直接参考。
整合swagger2
-
Maven依赖添加
在项目pom.xml中添加swagger2相应的依赖。
<!-- swagger2 主要依赖 --->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger2 默认主题样式 --->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger2 bootstrap风格主题样式 --->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.4</version>
</dependency>
-
swagger配置
在项目中添加swagger基础配置(SwaggerConfig.java)
package com.cooper.common;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* Swagger配置
*/
@Configuration
public class SwaggerConfig {
/**
* 通过 createRestApi函数来构建一个DocketBean
* 函数名,可以随意命名,喜欢什么命名就什么命名
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.cooper.module"))
.paths(PathSelectors.any())
.build()
.useDefaultResponseMessages(false)
.apiInfo(apiInfo());
}
/**
* 构建 api文档的详细信息函数
* @return ApiInfo
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("copper_sp 接口文档")
.version("v1.0.0")
.description("copper_sp 接口文档")
.build();
}
}
- 启动类中指定启用Swagger
在项目启动主类添加注解@EnableSwagger2指定启用swagger.
package com.cooper;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@SpringBootApplication
public class CooperSpApplication {
public static void main(String[] args) {
SpringApplication.run(CooperSpApplication.class, args);
}
}
此时我们启动项目，访问默认接口地址：xxxx/swagger-ui.html效果如下：
默认swagger接口文档
然后我们在访问一下bootstrap风格的接口地址：
xxxx/doc.html效果如下：
bootstrap风格接口文档
至此基本的整合我们就完成了。当然部分整合时可能会出现swagger-ui.html和doc.html访问地址报404.若出现此等问题，可以尝试将这两个路由添加到springboot的资源管理中，实现方式如下：通过实现WebMvcConfigurer类后重写addResourceHandlers方式实现：
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
写个接口文档试试
上面我们已经将swagger整合到springboot中了，接下来我们就写个接口文档看看效果。
- 接口文档
@ApiOperation(value = "分页获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "名称",dataType = "String"),
@ApiImplicitParam(name = "current",value = "当前页",required = true,dataType = "int",example = "1"),
@ApiImplicitParam(name = "size",value = "分页条数",required = true,dataType = "int",example = "10"),
})
@RequestMapping(value = "/list-with-page",method = {RequestMethod.GET,RequestMethod.POST})
@ResponseBody
public IPage<User> listWithPage(String name, Page<User> page){
return userService.listWithPage(name,page);
}
-
实际生成效果
image.png
image.png
至此springboot整合swagger2基本算完成了。我们可以稍许简单的方式编写接口文档了。更多swagger知识，待下次补充。
若有哪位好友有更方便快捷的方式欢迎赐教。
网友评论