SpringBoot整合Swagger-UI实现自动生成API文档

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档，号称世界上最流行的API框架。官网：https://swagger.io/

常用注解

@Api(tags = "xxx模块说明") ：用于修饰Controller类，生成Controller相关文档信息
@ApiOperation("xxx接口说明") ：用于修饰Controller类中的方法，生成接口方法相关文档信息
@ApiModelProperty(value = "xxx属性说明",hidden = true) ：作用在类方法和属性上，hidden设置为true可以隐藏该属性，用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
@ApiParam("xxx参数说明") ：作用在参数、方法和字段上，类似@ApiModelProperty，用于修饰接口中的参数，生成接口参数相关文档信息

基本结构
在这里插入图片描述

步骤

1）在自己的springboot项目中添加Swagger依赖

<!--Swagger-UI API文档生产工具-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

2）创建SwaggerConfig.java，用于配置Swagger

@Configuration
@EnableSwagger2//开启swagger
public class SwaggerConfig {

    /**
     * 配置Swagger配置
     * RequestHandlerSelectors.配置要扫描接口的方式
     * any():全部扫描
     * none():不扫描
     * withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
     * withMethodAnnotation:扫描方法上的注解
     *
     * PathSelectors.配置如何通过path过滤
     * any():任何请求都扫描
     * none():任何请求都不扫描
     * regex(final String pathRegex):通过正则表达式控制
     * ant(final String antPattern):通过ant()控制
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sakura.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置Swagger信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("SpringBoot整合SwaggerUI")
                .version("1.0")
                .build();
    }
}

3）给HelloController添加Swagger注解

@Api(tags = "HelloController",description = "测试Swagger")
@Controller
public class HelloController {

    @ApiOperation("输出hello")
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    @ResponseBody
    public String hello(){
        return "hello";
    }

    @ApiOperation("输出json数据")
    @RequestMapping(value = "/user",method = RequestMethod.GET)
    @ResponseBody
    public Map<String,Object> getUser(){
        HashMap<String,Object> modelMap = new HashMap<>();
        User user = new User("sakura","123");
        modelMap.put("infomation",user);
        return modelMap;
    }
}

4）启动springboot，并在浏览器中输入http://localhost:8080/swagger-ui.html
在这里插入图片描述

SpringBoot整合Swagger-UI实现自动生成API文档

猜你喜欢