SpringBoot集成Swagger的使用

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

Swagger能够在线自动生成 RESTFul接口的文档，同时具备测试接口的功能。

简单点来讲就是说，swagger是一款可以根据RESTFul风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。不是RESTFul风格也能生成文档。

一、添加依赖

     
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
           <version>2.8.0version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.8.0version>
        dependency>

二、启动类加上@EnableSwagger2注解

package com.example.fastjsondemo;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@EnableSwagger2
@SpringBootApplication
public class FastJsonDemoApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(FastJsonDemoApplication.class, args);
    }
 
}

三、application.properties文件配置

#路径匹配规则
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

四、创建控制层

package com.example.fastjsondemo.controller;
 
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试控制层
 */
@RestController
public class IndexController {
 
    @GetMapping("/index")
    public String hello(String name, Integer age) {
        return "name=" + name + ",age=" + age;
    }
}

四、测试

我们启动项目，然后浏览器访问:http://localhost:8080/swagger-ui.html

我们可以直接进行接口的测试

 五、Swagger配置

1.自定义设置文档头

package com.example.fastjsondemo.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des Swagger文档头部设置
 */
@Configuration
public class SwaggerConfig {
 
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                // 标题
                .title("我是标题")
                // 版本
                .version("1.0")
                // 描述
                .description("项目描述")
                // 联系人
                .contact(new Contact("qx","http://xxx.com","xx@qq.com"))
                .build();
        return docket.apiInfo(apiInfo);
    }
}

我们重新启动项目，然后访问Swagger地址。

 六、Swagger相关注解的认识

@Api:用在类上，说明该类的作用。

package com.example.fastjsondemo.controller;
 
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试控制层
 */
@Api(tags = {"测试接口"})
@RestController
public class IndexController {
 
    @GetMapping("/index")
    public String hello(String name, Integer age) {
        return "name=" + name + ",age=" + age;
    }
}

 @ApiModel：用在类上，表示对类进行说明，用于实体类中的参数接收说明。

@ApiModelProperty:用于字段、表示对属性的说明

package com.example.fastjsondemo.model;
 
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试的实体类
 */
@ApiModel(value = "IndexController", description = "地图实体")
@Data
public class Map {
 
 
    private String status;
    private String info;
    private String infocode;
    @ApiModelProperty(value = "省份")
    private String province;
    @ApiModelProperty(value = "城市")
    private String city;
    @ApiModelProperty(value = "地区码")
    private String adcode;
    @ApiModelProperty(value = "经纬度")
    private String rectangle;
}

package com.example.fastjsondemo.controller;
 
import com.example.fastjsondemo.model.Map;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试控制层
 */
 
@RestController
public class IndexController {
 
    @GetMapping("/index")
    public String hello(Map map) {
        return "hello";
    }
}

 @ApiOperation：用于对方法的说明。

package com.example.fastjsondemo.controller;
 
import com.example.fastjsondemo.model.Map;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试控制层
 */
 
@RestController
public class IndexController {
 
    @ApiOperation(value = "测试", notes = "测试描述")
    @GetMapping("/index")
    public String hello(Map map) {
        return "hello";
    }
}

@ApiImplicitParams和@ApiImplicitParam：用于对方法中的参数进行说明

• name：参数名，对应方法中单独的参数名称。

• value：参数中文说明。

• required：是否必填。

• paramType：参数类型，取值为 path、query、body、header、form。

• dataType：参数数据类型。

• defaultValue：默认值。

package com.example.fastjsondemo.controller;
 
import com.example.fastjsondemo.model.Map;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author qx
 * @date 2023/8/29
 * @des 测试控制层
 */
 
@RestController
public class IndexController {
 
    @ApiOperation(value = "测试", notes = "测试描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "string", paramType = "query", required = true, defaultValue = ""),
            @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "int", paramType = "query", required = true, defaultValue = "1")
    })
    @GetMapping("/index")
    public String hello(String name, Integer age) {
        return "name=" + name + ",age=" + age;
    }
}