spring boot项目中使用swagger2

在工作中的项目中，我们经常在一开始和前端的合作中写好接口文档，然后前端根据接口文档进行相关的对接工作，但是在后期的维护中，如果改动或者新增接口，可能直接和前端约定好，而不去维护接口文档，这样如果在将项目交付其他人的时候，这个接口文档可能是滞后的，增加了不少麻烦事。

一.介绍一下swagger

简单说明一下，Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档

还可以直接调试我们的API。

二.先看效果图

三.如何使用

首先介绍一下，使用的spring boot+maven构建的web项目，所以我们的步骤是：

第一步，pom文件中引入依赖

<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.8.0</version>
        </dependency>
           

第二步，写配置文件

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration implements WebMvcConfigurer {

    @Bean
    public Docket createRestApi() {
        // 参数配置
        List<Parameter> pars = new ArrayList<Parameter>();
        ParameterBuilder tokenPar = new ParameterBuilder();
	        tokenPar.name("Authorization").description("user token")
	    	.modelRef(new ModelRef("string")).parameterType("header") // header表示参数放在请求头
	    	.required(false); //header中的Authorization参数非必填，传空也可以
	        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enable) // 动态决定是否启动swagger
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//这个代码说明的我们扫描的哪些接口，我这行意思是扫描带@Api注解的接口类
                //也可以这样，说明扫描哪个包下的类 
                // .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);// 参数配置
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx接口文档")
                .description("xxx相关接口的文档")
                .termsOfServiceUrl("http://www.xxx.com")
                .version("1.0")
                .build();
    }

    /**
      * 静态资源配置
      */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
 
    }

}
           

第三步：增加相关的注解

import com.github.pagehelper.PageInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.ArrayList;
import java.util.List;

@Api(description = "用户接口 ")
@RestController
@RequestMapping("/admin/user")
public class AdminUserController {
    /**
     * 用户登录
     */
    @ApiOperation(value = "登录")
    @ApiImplicitParams({@ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String")})
    @PostMapping("/login")
    @SystemControllerLog(description = "/admin/user/login")
    public ResultVO login(String userName, String password){return null;}

    @ApiOperation(value = "例子")
    public ResultVO<DemoModel> demo(@RequestBody DemoModel demo){return demo;}
}

@Data
public class DemoModel {

    @ApiModelProperty(value = "defaultStr",example="mockStrValue")
    private String strDemo;

    @ApiModelProperty(example="1234343523",required = true)
    private Long longNum;

    @ApiModelProperty(example="111111.111")
    private Double doubleNum;

    @ApiModelProperty(example="2018-12-04T13:46:56.711Z")
    private Date date;
}
           

介绍一下相关的注解

@Api： 描述 Controller
@ApiIgnore： 忽略该 Controller，指不对当前类做扫描，忽略该参数，表示不对该参数扫描
@ApiOperation： 描述 Controller类中的 method接口
@ApiParam： 单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（   @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 描述 POJO对象
@ApiProperty： 描述 POJO对象中的属性值
@ApiImplicitParam： 描述单个入参信息
@ApiImplicitParams： 描述多个入参信息
@ApiResponse： 描述单个出参信息
@ApiResponses： 描述多个出参信息
@ApiError： 接口错误所返回的信息
           

接下就是启动项目，访问http://${host}/${contextPath}/swagger-ui.html这个地址