随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。
Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区,里面有许多强悍的贡献者。
Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 NAMES、ORDER 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
一、pom.xml引入基于maven的swagger依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
二、编写SwaggerConfig配置类
package com.foriseland.fsoa.pay.swagger;
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.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
@EnableWebMvc
@ComponentScan(basePackages = {"com.foriseland.fsoa.pay.controller"})
public class SwaggerConfig {
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("支付组", "", "");
return new ApiInfoBuilder()
.title("支付API接口")
.description("支付API接口")
.contact(contact)
.version("1.1.0")
.build();
}
}
注意:com.foriseland.fsoa.pay.controller 写自己的controller包路径。
三、在spring mvc配置xml里面加入Swagger配置
<!-- swagger -->
<bean class="com.foriseland.fsoa.pay.swagger.SwaggerConfig"></bean>
<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/"/>
注意:bean注入SwaggerConfig配置类
四、controller层的编写例子
类上面的注解
@Controller
@CrossOrigin
@Api(tags="账户信息控制类")
@RequestMapping("account")
public class AccountController{
方法上面的注解
@ApiOperation(value = "获取盈豆数量", notes = "获取盈豆数量", httpMethod = "POST")
@RequestMapping(value="getBeansNumber", method=RequestMethod.POST)
@ResponseBody
public void getBeansNumber(@RequestBody BeansCountDto info, HttpServletResponse response) {
}
}
五、启动项目
http://192.168.1.73:8080/fwas.pay.web.platform/swagger-ui.html
注意:这个我的ip、端口和项目名称,如果是自己的,就在访问地址最后加上swagger-ui.html在访问,到此就可以搞定测试了。