1.3 Spring项目使用Swagger-UI生成接口文档

前沿

每次做项目，无论是前后端测试，还是要生成后端的接口文档都不是一件特别方便的事情，而Swagger-ui这个简单的接口文档生成的框架为我们解决了这一系列问题。

简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用

1. 接口文档的动态在线生成。
2. 功能简单测试。

效果展示

下面就直接上代码吧

所需依赖

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

Swagger配置类

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket creatRestApi(){
        //        添加head参数start
        ParameterBuilder token = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        token.name("Authorization").description("返回的token")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        //根据每个方法名也知道当前方法在设置什么参数
        pars.add(token.build());

        //添加head参数end
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定接口的位置
                .apis(RequestHandlerSelectors.basePackage("com.swaggerdemo.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试后台接口文档")
                .description("前端根据接口进行测试")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

1. @EnableSwagger2 ：swagger2启动注解
2. @EnableWebMvc： 是使用Java 注解快捷配置Spring Webmvc的一个注解。在使用该注解后配置一个继承于WebMvcConfigurerAdapter的配置类即可配置好Spring Webmvc。
3. .apis; 是用来扫描controller包

三个注解的使用

@Api(tags = “xxx”)

使用在controller类上面，指明这个controller类的整体作用

@RestController
@RequestMapping("/admin")
@Api(tags = "用户管理接口")
public class UserController {

@ApiOperation(“xxx”)

使用在controller层的每个方法上，指明该接口的作用

@ApiOperation("获取所有用户信息")
    @GetMapping(value = "/getAll", name = "获取所有用户信息")
    public Object getAll() {
        return ResultVOUtil.success(userService.getAllUser());
    }

@ApiModelProperty(“xxx”)

使用在接受的参数上，对接收到的参数进行说明。

    /**
     * 学生学号
     */
    @NotNull(message = "学生id不能为空")
    @ApiModelProperty("学生学号")
    private String stuId;

    /**
     * 权限身份
     */
    @NotNull(message = "授权权限值不能为空")
    @ApiModelProperty("授权值")
    private Integer role;

访问路径都是 访问[ip]:[port]/swagger-ui.html即可 例如 localhost:8080/swagger-ui.html 同时要注意在整合的SpringSecurity中开放相关接口.