- 前后端分离的开发过程中,REST请求接口的定义,通过controller上面的RequestMapping进行交互。在开发过程中,需要像北向提供接口、以及接口相对应的参数。
- 同样,我们作为中台,可能同样需要调用南向的接口,需要交互的文档;如果文档都是手动编辑,那么这将是一项非常繁杂的工作。最好就在定义接口的时候,依靠swagger提供的方法将其实现。
1.实现功能需要的依赖
# 1.添加的依赖信息
<!--引入swagger的依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<!-- 上面的依赖,访问 http://ip:port/swagger-ui/index.html; 下面的依赖,访问 http://ip:port/doc.html-->
<!-- 一下两种都可以 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.8</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.5</version>
</dependency>
# 2.Application类上添加一个注解
/* 启动类上面添加注解: @EnableOpenAPI */
@SpringBootApplication
@EnableOpenApi
@MapperScan(value = {"edu.**.**.dao"})
public class Application {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
# 3.(可选)自定义首页Docket属性
@Configuration
public class Swagger3 extends WebMvcConfigurationSupport {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30).apiInfo(
new ApiInfoBuilder()
.contact(new Contact("Kern", "", "***@qq.com"))
.title("Swagger测试项目")
.build()
)
.select()
.apis(RequestHandlerSelectors.basePackage("指定项目的controller包"))
.paths(PathSelectors.any())
.build();
}
/**
* 防止@EnableMvc把默认的静态资源路径覆盖了,手动设置的方式
*
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOrigins("*")
.allowedMethods("GET", "POST", "PUT", "OPTIONS", "DELETE", "PATCH")
.allowCredentials(true).maxAge(3600);
}
}
2.swagger的常见使用
swagger常用标签:
- Api:标记在类上面,说明该类的作用。可标记一个Controller类作为Swagger文档资料
@Api(value ="/user", description="Operations about user")
- ApiOperation: 用于方法上,说明方法的作用,每个url资源的定义。
@ApiOperation(
value = "Find purchase order by ID",
notes = "For valid response try integer IDs with vlaue <=5 or >10",
response = order)
属性 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值,value将会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 配置多个Api,想改变显示的顺序位置 |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true,将在文档中隐藏 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
code | http的状态码,默认200 |
extensions | 扩展属性 |
- ApiParam:请求属性
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
- ApiResponse:响应配置
@ApiResponse(code = 400, message = "Invalid user supplied")
// 小型案例
@RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
public ResponseEntity<String> placeOrder(
@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
storeData.add(order);
return ok("");
}
3. 访问的url
- springfox-boot-starter
访问的路径: http://localhost:8188/swagger-ui/index.html
- swagger-bootstrap-ui
访问的路径: http://localhost:8188/doc.html 根据项目中设置的端口信息,修改下端口即可。