1. 前后端分离的开发过程中,REST请求接口的定义,通过controller上面的RequestMapping进行交互。在开发过程中,需要像北向提供接口、以及接口相对应的参数。
  2. 同样,我们作为中台,可能同样需要调用南向的接口,需要交互的文档;如果文档都是手动编辑,那么这将是一项非常繁杂的工作。最好就在定义接口的时候,依靠swagger提供的方法将其实现。

1.实现功能需要的依赖

  1. # 1.添加的依赖信息
  2. <!--引入swagger的依赖-->
  3. <dependency>
  4. <groupId>io.springfox</groupId>
  5. <artifactId>springfox-boot-starter</artifactId>
  6. <version>3.0.0</version>
  7. </dependency>
  8. <!-- 上面的依赖,访问 http://ip:port/swagger-ui/index.html; 下面的依赖,访问 http://ip:port/doc.html-->
  9. <!-- 一下两种都可以 -->
  10. <dependency>
  11. <groupId>com.github.xiaoymin</groupId>
  12. <artifactId>knife4j-spring-boot-starter</artifactId>
  13. <version>2.0.8</version>
  14. </dependency>
  15. <dependency>
  16. <groupId>com.github.xiaoymin</groupId>
  17. <artifactId>swagger-bootstrap-ui</artifactId>
  18. <version>1.9.5</version>
  19. </dependency>
  1. # 2.Application类上添加一个注解
  2. /* 启动类上面添加注解: @EnableOpenAPI */
  3. @SpringBootApplication
  4. @EnableOpenApi
  5. @MapperScan(value = {"edu.**.**.dao"})
  6. public class Application {
  7. public static void main(String[] args) {
  8. SpringApplication.run(SwaggerApplication.class, args);
  9. }
  10. }
  1. # 3.(可选)自定义首页Docket属性
  2. @Configuration
  3. public class Swagger3 extends WebMvcConfigurationSupport {
  4. @Bean
  5. public Docket docket() {
  6. return new Docket(DocumentationType.OAS_30).apiInfo(
  7. new ApiInfoBuilder()
  8. .contact(new Contact("Kern", "", "***@qq.com"))
  9. .title("Swagger测试项目")
  10. .build()
  11. )
  12. .select()
  13. .apis(RequestHandlerSelectors.basePackage("指定项目的controller包"))
  14. .paths(PathSelectors.any())
  15. .build();
  16. }
  17. /**
  18. * 防止@EnableMvc把默认的静态资源路径覆盖了,手动设置的方式
  19. *
  20. * @param registry
  21. */
  22. @Override
  23. protected void addResourceHandlers(ResourceHandlerRegistry registry) {
  24. // 解决静态资源无法访问
  25. registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
  26. // 解决swagger无法访问
  27. registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
  28. // 解决swagger的js文件无法访问
  29. registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
  30. }
  31. @Override
  32. public void addCorsMappings(CorsRegistry registry) {
  33. registry.addMapping("/**")
  34. .allowedOrigins("*")
  35. .allowedMethods("GET", "POST", "PUT", "OPTIONS", "DELETE", "PATCH")
  36. .allowCredentials(true).maxAge(3600);
  37. }
  38. }

2.swagger的常见使用

swagger常用标签:

  • Api:标记在类上面,说明该类的作用。可标记一个Controller类作为Swagger文档资料
    @Api(value ="/user", description="Operations about user")
  • ApiOperation: 用于方法上,说明方法的作用,每个url资源的定义。
  1. @ApiOperation(
  2. value = "Find purchase order by ID",
  3. notes = "For valid response try integer IDs with vlaue <=5 or >10",
  4. 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")
  1. // 小型案例
  2. @RequestMapping(value = "/order", method = POST)
  3. @ApiOperation(value = "Place an order for a pet", response = Order.class)
  4. @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  5. public ResponseEntity<String> placeOrder(
  6. @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
  7. storeData.add(order);
  8. return ok("");
  9. }

3. 访问的url

  1. springfox-boot-starter

访问的路径: http://localhost:8188/swagger-ui/index.html

  1. swagger-bootstrap-ui

访问的路径: http://localhost:8188/doc.html 根据项目中设置的端口信息,修改下端口即可。