Swagger-UI

Swagger-UI

Swagger是啥 ？ Swagger 是一个用来生成接口文档的开源框架 。前后端分离的情况下，前端通过后端编写的API文档，了解接口的调用规则，但是传统的接口文档，是由后按程序员编写，是个枯燥的体力活。Swagger解决了这个痛点，根据接口方法上写的相关注解 自动生成接口文档，而且还支持测试。

1、新增依赖

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

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

2、新增配置

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
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
@EnableWebMvc
public class SwaggerConfig  implements WebMvcConfigurer {
    
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//接口所在路径
            .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("石河子大学SpringBoot商城")//文档说明
            .version("1.0.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/");
        //WebMvcConfigurer.super.addResourceHandlers(registry);
    }
    
    
    
    
}

3、新增注解

@Api 注解 用在控制器类上 @ApiOperation 注解 用在接口方法上

@Api(value = "用户接口",tags = "用户接口")
@RestController
@CrossOrigin
public class UserController {

    @Autowired
    IUserService userService;

    @ApiOperation("用户列表")
    @RequestMapping(value = "/users",method = RequestMethod.GET)
    public CommonResult   list(@RequestParam(value = "pageNum",required = false,defaultValue = "1")  Integer  pageNum ,
                               @RequestParam(value = "pageSize",required = false,defaultValue = "10")  Integer  pageSize
                               ){
        List<User>  userList  =  userService.findListByPage(pageNum,pageSize);
        return CommonResult.success("分页查询用户数据成功",userList);

    }

备注：我个人只喜欢使用，@Api和 @ApiOperation 其他注解很少使用，我怕代码太乱，降低可读性

其他注解介绍:

@Api 用在Controller 类上

@ApiOperation 用在方法上

@ApiParam 用在参数上

@ApiImplicitParams、@ApiImplicitParam 用在请求的方法上，包含一组参数说明

@ApiModel、@ApiModelProperty 用在实体类和实体类属性上

4、访问接口文档

输入地址：http://localhost:8080/swagger-ui.html#/ 注意ip地址和端口 换成你自己的环境

springboot+swagger No operations defined in spec!

报错页面如下
原因：swagger的配置类找不到路径
解决办法：
1.将@ComponentScan(basePackages = {"com.example.springboot.config"})中的basePackages改为配置类的包路径
2.再将配置类的.apis(RequestHandlerSelectors.basePackage(""))的basePackage写上controller层的包路径。
报错页面如下
原因：swagger的配置类找不到路径

解决办法：
1.将@ComponentScan(basePackages = {“com.example.springboot.config”})中的basePackages改为配置类的包路径
2.再将配置类的.apis(RequestHandlerSelectors.basePackage(""))的basePackage写上controller层的包路径。