随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系,变成了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