1 简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
2 pom文件添加Swagger2依赖
<properties>
<java.version>1.8</java.version>
<swagger2.version>2.9.2</swagger2.version>
</properties>
<!--swagger2 相关依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
3 创建Swagger2配置类
swagger配置类建议放在和application.java启动类在同一个包里面，这样会被自动扫描到。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 初始化创建Swagger Api
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 详细信息定制
.apiInfo(apiInfo())
.select()
// 指定当前包路径
.apis(RequestHandlerSelectors.basePackage("com.tickstep.demo"))
// 只扫描有注解的api，用这种方式更灵活//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
.title("Spring boot 集成 Swagger2 API工具测试")
.description("本接口文档是从代码自动构建而来，如果接口有更改请更新后台")
.contact(new Contact("多啦E梦的博客", null, null))
.version("0.0.1")
.build();
}
}
启动application，然后直接访问 http://localhost:8280/swagger-ui.html 即可查看swagger自动生成的api接口文档
4 更改Swagger访问路径
Swagger默认是访问路径是/swagger-ui.html，但有时候我们需要更改这个接口访问路径，以方便对后台URL接口的统一管理。
打开 springfox-swagger-ui.jar 包，我们可以看出swagger web 端UI的资源全部在这里面
springfox-swagger-ui.jar
这样思路就简单了，可以采取两种方法
1，我们可以把这个里面的资源全部拷贝到我们的resources目录，然后更改对应的路径映射即可（可能有些资源文件也需要改一下）
2，我们直接写个ModelAndView接口进行内部重定向
第2种方式侵入性低，我们选用这种
直接在SwaggerConfig.java文件增加以下代码
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 指定文档访问URL路径
// 例如指定以下路径，则通过这个URL访问：http://localhost:8280/actuator/swagger/swagger-ui.html
private static final String DEFAULT_PATH = "/actuator/swagger";
/**
* SwaggerUI资源访问
*/
@Bean
public SimpleUrlHandlerMapping swaggerUrlHandlerMapping(ServletContext servletContext,
@Value("${swagger.mapping.order:10}") int order) throws Exception {
SimpleUrlHandlerMapping urlHandlerMapping = new SimpleUrlHandlerMapping();
Map<String, ResourceHttpRequestHandler> urlMap = new HashMap<>();
// webjars
PathResourceResolver pathResourceResolver = new PathResourceResolver();
pathResourceResolver.setAllowedLocations(new ClassPathResource("META-INF/resources/webjars/"));
// pathResourceResolver.setUrlPathHelper(new UrlPathHelper());
ResourceHttpRequestHandler resourceHttpRequestHandler = new ResourceHttpRequestHandler();
resourceHttpRequestHandler.setLocations(Arrays.asList(new ClassPathResource("META-INF/resources/webjars/")));
resourceHttpRequestHandler.setResourceResolvers(Arrays.asList(pathResourceResolver));
resourceHttpRequestHandler.setServletContext(servletContext);
resourceHttpRequestHandler.afterPropertiesSet();
//设置新的路径
urlMap.put(DEFAULT_PATH + "/webjars/**", resourceHttpRequestHandler);
// resources
PathResourceResolver pathResourceResolverOfRes = new PathResourceResolver();
pathResourceResolverOfRes.setAllowedLocations(new ClassPathResource("META-INF/resources/"));
// pathResourceResolver.setUrlPathHelper(new UrlPathHelper());
ResourceHttpRequestHandler resourceHttpRequestHandlerOfRes = new ResourceHttpRequestHandler();
resourceHttpRequestHandlerOfRes.setLocations(Arrays.asList(new ClassPathResource("META-INF/resources/")));
resourceHttpRequestHandlerOfRes.setResourceResolvers(Arrays.asList(pathResourceResolverOfRes));
resourceHttpRequestHandlerOfRes.setServletContext(servletContext);
resourceHttpRequestHandlerOfRes.afterPropertiesSet();
//设置新的路径
urlMap.put(DEFAULT_PATH + "/**", resourceHttpRequestHandlerOfRes);
urlHandlerMapping.setUrlMap(urlMap);
//调整DispatcherServlet关于SimpleUrlHandlerMapping的排序
urlHandlerMapping.setOrder(order);
return urlHandlerMapping;
}
/**
* SwaggerUI接口访问
*/
@Controller
@ApiIgnore
@RequestMapping(DEFAULT_PATH)
public static class SwaggerResourceController implements InitializingBean {
@Autowired
private ApiResourceController apiResourceController;
@Autowired
private Environment environment;
@Autowired
private DocumentationCache documentationCache;
@Autowired
private ServiceModelToSwagger2Mapper mapper;
@Autowired
private JsonSerializer jsonSerializer;
private Swagger2Controller swagger2Controller;
@Override
public void afterPropertiesSet() {
swagger2Controller = new Swagger2Controller(environment, documentationCache, mapper, jsonSerializer);
}
/**
* 首页
*/
@RequestMapping
public ModelAndView index() {
ModelAndView modelAndView = new ModelAndView("redirect:" + DEFAULT_PATH + "/swagger-ui.html");
return modelAndView;
}
@RequestMapping("/swagger-resources/configuration/security")
@ResponseBody
public ResponseEntity<SecurityConfiguration> securityConfiguration() {
return apiResourceController.securityConfiguration();
}
@RequestMapping("/swagger-resources/configuration/ui")
@ResponseBody
public ResponseEntity<UiConfiguration> uiConfiguration() {
return apiResourceController.uiConfiguration();
}
@RequestMapping("/swagger-resources")
@ResponseBody
public ResponseEntity<List<SwaggerResource>> swaggerResources() {
return apiResourceController.swaggerResources();
}
@RequestMapping(value = "/v2/api-docs", method = RequestMethod.GET, produces = {"application/json", "application/hal+json"})
@ResponseBody
public ResponseEntity<Json> getDocumentation(
@RequestParam(value = "group", required = false) String swaggerGroup,
HttpServletRequest servletRequest) {
return swagger2Controller.getDocumentation(swaggerGroup, servletRequest);
}
}
}
直接更改这个路径配置即可更改swagger的访问路径
private static final String DEFAULT_PATH = "/actuator/swagger";
重新运行application，然后接口访问
http://localhost:8280/actuator/swagger/swagger-ui.html
swagger ui
5 集成上传File文件接口
我们Controller上备注接口描述的时候，file比较特殊。需要按照以下规则进行备注。
dataType是"__file"类型：
@PostMapping("/fileUpload")
@ApiImplicitParams({@ApiImplicitParam(paramType = "form", dataType="__file", name = "file",
value = "材料文件啊", required = false)})
public String fileUpload(MeterialUploadForm form) {
return form.getFile() == null ? "file is null" : form.getFile().getOriginalFilename();
}
6 资源
代码示例请访问：https://gitlab.com/feny-blog/springboot-integrate-swagger.git
