swagger扫描路径设置（良心文章前后分离最详尽的Swagger2使用案例）

本号主要用于分享企业中常用的技术，更加侧重于实用，欢迎关注，方便浏览更多实用的历史文章。如果你不会Swagger或者掌握的不全面，那么这是一份详尽的文章，让你一次恶补全部知识，请认真学习一下，让大家能学到具体实际有用的知识是我的责任。

前后端分离，前端和后端API沟通目前企业中几乎都是使用Swagger2。本文主要讲解一下几个案例，基本上工作中都会用到：

1. Swagger2基本的集成
2. 对Swagger2配置安全访问
3. 聚合多个项目

1. 添加入Swagger2的依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>

2. Swagger2Config

@Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .groupName("demo") .apiInfo(apiInfo()) .select() // 设置basePackage会将包下的所有类的所有方法作为Api // .apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller")) // 只有标记@ApiOperation才会暴露出给swagger .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.regex("/api/.*")) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API接口文档") .description("RESTful风格接口") .termsOfServiceUrl("https://blog.csdn.net/vbirdbest") // 服务条款网址 .version("1.0") .contact(new Contact("mengday", "httphttp://wwww.xxx.com", "xxx@gmail.com")) .build(); } }

3. UserController

@RestController @RequestMapping("/api/v1/users") @Api(value = "User API接口", tags = "user", description = "User API接口") public class UserController { @ApiOperation(value = "用户登录", notes = "用户登录接口") @ApiResponses({ @ApiResponse(code = 0, message = "success"), @ApiResponse(code = 10001, message = "用户名错误", response = IllegalArgumentException.class), @ApiResponse(code = 10002, message = "密码错误") }) @PostMapping(value = "/login") public String login(@ApiParam(name = "username", value = "用户名", required = true) @RequestParam String username, @ApiParam(name = "password", value = "密码", required = true) @RequestParam String password){ return "{'username':'" username "', 'password':'" password "'}"; } @ApiOperation(value = "修改用户信息", notes = "修改用户信息") @ApiImplicitParams({ @ApiImplicitParam(dataTypeClass = String.class, paramType = "header", name = "phone", required = true, value = "手机号"), @ApiImplicitParam(dataTypeClass = String.class, paramType = "query", name = "nickname", required = true, value = "nickname", defaultValue = "双击666"), @ApiImplicitParam(dataTypeClass = String.class, paramType = "path", name = "platform", required = true, value = "平台", defaultValue = "PC"), @ApiImplicitParam(dataTypeClass = String.class, paramType = "body", name = "password", required = true, value = "密码") }) @PutMapping(value = "/{platform}/regist") public String regist(@RequestHeader String phone, @RequestParam String nickname, @PathVariable String platform, @RequestBody String password){ return "{'username':'" phone "', 'nickname':'" nickname "', 'platform': '" platform "', 'password':'" password "'}"; } @ApiOperation(value = "用户列表", notes = "查询用户列表") @GetMapping(value = "/list") public String getUserList(PagerIDto pager){ return "[{'id': " pager.getPage() ", 'username': 'zhangsan" pager.getSize() "'}]"; } @ApiOperation(value = "删除用户", notes = "删除用户") @DeleteMapping("/{id}") public String removeUser(@PathVariable Long id){ return "success"; } @ApiIgnore @RequestMapping("/ignoreApi") public String ignoreApi(){ return "docs"; } }

4. 启动应用程序并访问swagger-ui.html

5. 为swagger-ui增加密码

5.1 pom.xml

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency>

5.2 application.yml

spring: security: basic: path: /swagger-ui.html enabled: true user: name: admin password: 123456

5.3 WebSecurityConfigurerAdapter

/** * Spring Security 会拦截swagger-ui.html 同样也会拦截api，这里将或略掉/api/下的所有子路径 */ @EnableWebSecurity @Configuration public class CustomWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter { @Override public void configure(WebSecurity web) throws Exception { super.configure(web); web.ignoring().antMatchers("/api/v1/**"); } }

5.4 重启项目再次访问swagger-ui

访问 http://localhost:8080/swagger-ui.html 会跳转到 http://localhost:8080/login 输入application.yml配置的用户名密码即可跳转到到swagger-ui.html

apis(RequestHandlerSelectors.basePackage(“com.example.demo2.controller”)) 会将包下的所有Controller类带有@RequestMapping或者XxxMapping都会给暴露给swagger，如果想部分类暴露出去部分不暴露出去，只能将不暴露的controller放到其他package中，放在同一个package是做不到的。

apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)): 只有在类上使用@Api注解标注并且在方法上使用@ApiOperation注解才会暴露给swagger，这种方式没有包名的限制，可以将需要暴露的接口分散到各个包里，只要类上有@Api注解方法上有@ApiOperation注解就能暴露出来，如果不想暴露出来就不用使用这两个注解。

5. swagger 聚合多个项目

现在的项目一般都是微服务，swagger可以做到将多个项目合并到一个swagger上，这样便于接口的使用。

• 对于低版本的swagger可以直接改造源码，swagger实现多项目api管理：https://blog.csdn.net/liufei198613/article/details/78898789 对于2.2.2版本可以直接改造源码https://testerhome.com/topics/9427
• 高版本的可以通过SwaggerResourcesProvider来实现，具体步骤如下

本示例只使用了Spring Boot, 后面可以结合spring-cloud-zuul来使用。

首先准备两个api项目(platform-user-server、platform-order-server)，并且每个项目都配置好swagger，然后再使用一个聚合的api项目(platform-api-gateway)来聚合这两个api，这样只需查看聚合api上对应的swagger ui即可。

一：platform-user-server

1. maven

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>

2. application.properties

server.port=8081

3. Configuration

@Configuration public class CORSConfiguration { @Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration corsConfiguration = new CorsConfiguration(); // 1 设置访问源地址 corsConfiguration.addAllowedOrigin("*"); // 2 设置访问源请求头 corsConfiguration.addAllowedHeader("*"); // 3 设置访问源请求方法 corsConfiguration.addAllowedMethod("*"); // 4 对接口配置跨域设置 source.registerCorsConfiguration("/**", corsConfiguration); return new CorsFilter(source); } } @Configuration public class Swagger2Configuration { @Bean public Docket shopRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.platform.user")) .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { Contact contact = new Contact("mengday", "https://blog.csdn.net/vbirdbest", "mengday.zhang@gmail.com"); return new ApiInfoBuilder() .title("用户API") .description("用户API") .termsOfServiceUrl("http://localhost:8081/swagger-ui.html") .contact(contact) .version("1.0") .build(); }

4. Application

@EnableSwagger2 @SpringBootApplication public class PlatformUserServerApplication { public static void main(String[] args) { SpringApplication.run(PlatformUserServerApplication.class, args); } }

5. controller

@RestController @RequestMapping("/user") @Api(description = "用户API") public class UserController { @ApiOperation(value = "用户登录", notes = "用户登录", produces = MediaType.APPLICATION_JSON_UTF8_VALUE) @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "body", dataType = "String"), @ApiImplicitParam(name = "password", value = "密码", required = true, paramType = "body", dataType = "String") }) @PostMapping("/login") public String login(String username, String password) { return "success"; } }

6. 访问swagger

http://localhost:8081/swagger-ui.html

注意：swagger不要使用太高的版本，不建议使用2.8.0以上的版本，不然很可能会报如下错误，即使低版本也可能会报该错误。Chrome报错，遇到这个错误可以尝试清除缓存或者使用其他浏览器，这个问题很多人都遇到了，也没找到有效的解决方案，自己在测试的时候就一会好使，一会又不好使，祝你好运。

二：platform-order-server

1. maven

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>

2. application.properties

server.port=8082

3. Configuration

@Configuration public class CORSConfiguration { @Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration corsConfiguration = new CorsConfiguration(); // 1 设置访问源地址 corsConfiguration.addAllowedOrigin("*"); // 2 设置访问源请求头 corsConfiguration.addAllowedHeader("*"); // 3 设置访问源请求方法 corsConfiguration.addAllowedMethod("*"); // 4 对接口配置跨域设置 source.registerCorsConfiguration("/**", corsConfiguration); return new CorsFilter(source); } } @Configuration public class Swagger2Configuration { @Bean public Docket shopRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.platform.order")) .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { Contact contact = new Contact("mengday", "https://blog.csdn.net/vbirdbest", "mengday.zhang@gmail.com"); return new ApiInfoBuilder() .title("订单API") .description("订单API") .termsOfServiceUrl("http://localhost:8082/swagger-ui.html") .contact(contact) .version("1.0") .build(); } }

4. Application

@EnableSwagger2 @SpringBootApplication public class PlatformOrderServerApplication { public static void main(String[] args) { SpringApplication.run(PlatformOrderServerApplication.class, args); } }

5. controller

@RestController @RequestMapping("/shoppingcart") @Api(description = "购物车API") public class ShoppingCartController { @ApiOperation(value = "加入购物车", notes = "加入购物车", produces = MediaType.APPLICATION_JSON_UTF8_VALUE) @ApiImplicitParams({ @ApiImplicitParam(name = "barcode", value = "条形码", required = true, paramType = "body", dataType = "String"), @ApiImplicitParam(name = "quantity", value = "数量", required = true, paramType = "body", dataType = "Integer") }) @PostMapping("/add") public String addShoppingCart(String barcode, Integer quantity) { return "success"; } }

6. 访问swagger

三：platform-api-gateway

1. maven

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>

2. application.properties

server.port=8080

3. Application

@EnableSwagger2 @SpringBootApplication public class PlatformApiGatewayApplication { public static void main(String[] args) { SpringApplication.run(PlatformApiGatewayApplication.class, args); } }

4. configuration

@Configuration public class CORSConfiguration { @Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration corsConfiguration = new CorsConfiguration(); // 1 设置访问源地址 corsConfiguration.addAllowedOrigin("*"); // 2 设置访问源请求头 corsConfiguration.addAllowedHeader("*"); // 3 设置访问源请求方法 corsConfiguration.addAllowedMethod("*"); // 4 对接口配置跨域设置 source.registerCorsConfiguration("/**", corsConfiguration); return new CorsFilter(source); } } @Configuration public class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { Contact contact = new Contact("mengday", "https://blog.csdn.net/vbirdbest", "mengday.zhang@gmail.com"); return new ApiInfoBuilder() .title("项目名称") .description("Swagger多项目聚合") .termsOfServiceUrl("http://localhost:8080") .contact(contact) .version("1.0") .build(); } } @Component @Primary public class DocumentationConfiguration implements SwaggerResourcesProvider { @Override public List<SwaggerResource> get() { List resources = new ArrayList<>(); resources.add(swaggerResource("用户API", "http://localhost:8081/v2/api-docs", "2.0")); resources.add(swaggerResource("购物车API", "http://localhost:8082/v2/api-docs", "2.0")); return resources; } private SwaggerResource swaggerResource(String name, String location, String version) { SwaggerResource swaggerResource = new SwaggerResource(); swaggerResource.setName(name); swaggerResource.setLocation(location); swaggerResource.setSwaggerVersion(version); return swaggerResource; } }

5. 访问swagger

代码已经贴出来了，如果您在手机上不方面看代码，建议收藏后在PC上浏览。,