关于Swagger
Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
- Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区,里面有许多强悍的贡献者。
Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
注意:用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。
以下是SSM的前后端分离项目中使用swagger的示例:
1, 首先在MAVEN 项目的pom文件中引入相关依赖,依赖如下:
(其中的jackson依赖是用于支持RESTful接口实现提供JSON格式数据的)
<!-- 第五部分:JSON,jackson依赖 --> <!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.9.8</version> </dependency> <!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.9.8</version> </dependency> <!-- 第六部分:swagger-api依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
2,创建配置类SwaggerConfig和WebMvcConfig
SwaggerConfig
package com.HW_CloudComputer.webconfig.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration //必须存在 @EnableSwagger2 //必须存在 @EnableWebMvc //必须存在 //必须存在 扫描的API controller 包 @ComponentScan(basePackages = {"com.HW_CloudComputer.api"}) public class SwaggerConfig { @Bean public Docket customDocket(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); } private ApiInfo apiInfo(){ Contact contact = new Contact("CuiTg","https://www.huawei.com/cn/","Ctiangui@shu.edu.cn"); return new ApiInfoBuilder() .title("HW_CloudComputer项目的API接口") .description("API接口") .contact(contact) .version("1.1.0") .build(); } }
WebMvcConfig
package com.HW_CloudComputer.webconfig.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebMvcConfig implements WebMvcConfigurer { public void addResourceHandlers(ResourceHandlerRegistry registry){ registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
swagger-ui.html为API文档的页面
3,注意要让spring启动配置时自动扫描以上两个配置类
<!-- 扫描swagger的配置包 --> <context:component-scan base-package="com.HW_CloudComputer.webconfig.config" />
4,编写controller,在controller中进行相应配置以便生成API文档
package com.HW_CloudComputer.api; import com.HW_CloudComputer.model.TimeDelay; import com.HW_CloudComputer.service.RealTimeService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; @RestController @Api(value = "实时查询模块",description = "实时查询模块的接口信息" ) @RequestMapping("realtime") public class RealTimeController { @Autowired private RealTimeService realTimeService; @ApiOperation(value = "获取实时信息",notes = "获取云电脑的实时时延数据") @RequestMapping(method = RequestMethod.GET) public TimeDelay realTime(){ return realTimeService.findRealTime(); } }
@RestController @Api(value = "参数查询模块",description = "参数查询模块的接口信息" ) @RequestMapping("/argsquery") public class ArgsQueryController { @Autowired private ArgsQueryService argsQueryService; @ApiOperation(value = "以“刻”为刻度,返回数据",notes = "根据起始与结束时间获取云电脑时延数据,时间刻度为“刻") @ApiImplicitParams({ @ApiImplicitParam(name = "start_name",dataType = "String",paramType = "path",value = "查询起始时间,格式范例:2019年4月17日14点30分,start_name=201904171430"), @ApiImplicitParam(name = "end_time",dataType = "String",paramType = "path",value = "查询起始时间,格式范例:2019年4月17日14点30分,end_name=201904171430") }) @RequestMapping(value = "/quarter/{start_time}/{end_time}",method = RequestMethod.GET) public List<TimeDelay> showManyQuarter(@PathVariable("start_time") String start_time, @PathVariable("end_time") String end_time){ return argsQueryService.findMany(start_time,end_time); }
5,项目完成部署到tomcat中以后访问http://localhost:8080/swagger-ui.html即可访问API文档
在web.xml中修改和新增配置:
将*.do改为/
<servlet-mapping>
<servlet-name>springmvc</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>