-What’s Swagger

由于前后端分离的开发模式越来越普遍，所以前后端之间的联系大多都是通过接口文档来进行实现。而在实际开发过程中，开发接口文档与最终成型的文档需要不断地调整和维护，造成了极为不便的接口文档同步工作。
Swagger就是为了解决这种情况而应用的，说白了就是为了保持开发接口和接口文档说明实时同步的作用。

-Let’s start

我们用2.1.2版本的SpringBoot做Swagger环境的集成，首先在pom文件中引入相关的Swagger依赖:

• Swagger依赖引入

<!-- swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.5.0</version>
</dependency>

<!--swagger-ui-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.5.0</version>
</dependency>

我目前选用的是2.5.0版本的Swagger，之前选用的2.7.0版本遇到了诸多不可预见的问题，所以进行了降版本处理。

• 在config包下写Swagger的配置类:

package com.huayun.safety.config;

import io.swagger.annotations.ApiOperation;
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;


/**
 * @author [email protected]
 * @data 2019/1/28 11:36
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        System.out.println("======  SWAGGER CONFIG  ======");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("填写你的接口文档标题")
                .description("填写你的接口文档说明")
                .contact(new Contact("作者名/团队名", "服务访问链接", "联系邮箱号"))
                .version("版本号")
                .build();
    }

}

在此请注意，@EnableSwagger2这个注解至关重要，这是作为启用Swagger的要素。

• 在Controller控制层的java文件中写Swagger对应的接口说明，例如:

@Api(description = "用户服务")
@RestController
@RequestMapping(value = "/user")
public class UserController {

在这个UserController类中，类名上的@Api就是Swagger提供的注解，在description属性中写入你要描述关于该控制器的信息。
在方法中，可以用@ApiOperation说明该方法的用途，例如:

@ApiOperation(value = "获取用户列表",notes = "获取用户列表",httpMethod = "GET")
@RequestMapping(value = "/getList",method = RequestMethod.GET)
public List<ADomain> getUserList(){
    return aService.getUserList();
}

这是针对无参的方法调用在Swagger的写法，如果我们要进行传参，那么需要在参数前面加一个@ModelAttribute的注解，例如：

@ApiOperation(value = "用户登录",notes = "用户登录",httpMethod = "GET")
@RequestMapping(value = "/login",method = RequestMethod.GET)
public Result<ADomain> login(@ModelAttribute ADomain aDomain){
    if(StringUtils.isEmpty(aDomain.getUserName()) && StringUtils.isEmpty(aDomain.getUserPassword())){
        return Result.createFailed("-1","登录失败，用户名/密码不准为空");
    }
    return Result.createSucc(aDomain);
}

基本的Swagger使用就是如此，最后我们进行测试工作，启动项目之后访问 http://localhost:8080/swagger-ui.html
就能够看到如下画面:

这就说明我们Swagger集成成功了。

参考资料：

快速了解Swagger
https://blog.****.net/i6448038/article/details/77622977

Swagger常用注解说明
https://blog.****.net/u014231523/article/details/76522486

Swagger官方网站
https://swagger.io/