Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
- Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区,里面有许多强悍的贡献者。
Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息
注意:用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。
弄了很久终于弄出来了,网上看了很多springboot整合的例子,自己也写了demo,整合起来很容易。
但是在mvc项目中整合遇到了一些问题,第一次引入后发现项目启动不了,最后查出是配置文件的问题,修改好application.xml和springmvc.xml中的配置,然后swagger-ui.html页面显示不出来。
这次记录一下mvc项目中是如何引入的:
1.首先引入依赖,在pom.xml中添加
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.需要写一个swagger的配置类
package com.*.swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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
public class MySwaggerConfig {
@Bean
public Docket userApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.*.controller")) //指明controller所在的包
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("api接口文档")
// 设置联系人
.contact(new Contact("联系人姓名", "liudehua","liudehua@qq.com"))
// 描述
.description("controller层接口如下")
// 定义版本号
.version("1.0").build();
}
}
3.接下来配置spring-mvc.xml
<!--swagger配置 -->
<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>
<mvc:default-servlet-handler />
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:resources mapping="/swagger/**" location="classpath:/swagger/"/>
4.在applicationContext.xml中配置
<context:component-scan base-package="com.chetubao" use-default-filters="false">
<context:exclude-filter type="assignable" expression="com.chetubao.swagger.MySwaggerConfig"/>
</context:component-scan>
5.下载swagger-ui组件将dist项目下的所有文件拷贝到项目中,我这里在resources新建swagger,如下图:
然后将index.html中的url改为:http://localhost:8080/v2/api-docs
6.编写一个测试类:
package com.*.controller.base;
import com.*.entity.CarListInfo;
import com.*.service.CarListInfoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.solar.bean.JsonResult;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
@RequestMapping("/test")
@Api(value = "测试swaggerApi")
public class TestController {
@Autowired
private CarListInfoService carListInfoService;
@ResponseBody
@RequestMapping(value = "/get",method = RequestMethod.GET)
@ApiOperation(value = "根据id获取CarListInfo")
@ApiImplicitParam(paramType = "query",name = "id" ,value = "车系id",required = true)
public JsonResult getCarListInfo(@RequestParam(value = "id") String id){
CarListInfo info = carListInfoService.getById(id);
return JsonResult.success(info);
}
}
启动项目,访问http://localhost:8080/v2/api-docs返回json数据
访问http://localhost:8080/swagger/index.html#显示swagger-ui页面
到这里就完成了swagger的整合,如果有问题欢迎评论留言,不对的地方请大家指正