Java工程师知识树 / 项目学习

概念和作用

概念:

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务.

作用:

• 支持 API 自动生成同步的在线文档.另外一种方式,使用编写Office文档来提供接口文档.
• 提供 Web 页面在线测试 API.另外一种常用方式使用postman测试接口.

SpringBoot集成Swagger

集成最低要求是可以使用,类似一个Hello World项目.

注:

1. jdk 需要使用1.8或以上版本
2. swagger2的3.0版本的访问地址/swagger-ui/index.html
   2.x之前访问地址/swagger-ui.html
3. maven文件配置

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

4. Application启动应用类上面加入@EnableOpenApi注解

@EnableOpenApi// 只需要在Application启动应用类配置
@SpringBootApplication
public class Swagger3Application {
    public static void main(String[] args) {
        SpringApplication.run(Swagger3Application.class, args);
    }
}

项目启动后的效果为:

SpringBoot配置Swagger

自定义配置类

import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.lang.reflect.Field;
import java.util.List;

@Configuration
public class Swagger3Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select() // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                /*
                basePackage(final String basePackage) // 根据包路径扫描接口
                any() // 扫描所有，项目中的所有接口都会被扫描到
                none() // 不扫描接口
                // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                withMethodAnnotation(final Class<? extends Annotation> annotation)
                // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                withClassAnnotation(final Class<? extends Annotation> annotation)
                 */
                .apis(RequestHandlerSelectors.basePackage("com.study.swagger3.controller"))// basePackage 根据包路径扫描接口
                /*
                any() // 任何请求都扫描
                none() // 任何请求都不扫描
                regex(final String pathRegex) // 通过正则表达式控制
                ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.any())// 配置如何通过path过滤,即这里扫描所有请求 any none ant regex
                .build();
    }

    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("文档描述")
                .contact(new Contact("hughJin", "#", "1369766951@qq.com"))
                .version("1.0")
                .build();
    }

    /**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                            .excludePathPatterns("/swagger**/**")
                            .excludePathPatterns("/webjars/**")
                            .excludePathPatterns("/v3/**")
                            .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

常用Swagger注解与说明

Swagger注解代码实例

import com.study.swagger3.dto.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@Api(value = "@Api：用在控制器类上，表示对类的说明", tags = "Swagger测试之用户信息管理API")
@RestController
@RequestMapping("/user")
public class SwaggerController {

    @ApiIgnore    // 忽略这个API
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    @GetMapping(value = "/swaggerGet/{name}")
    @ApiOperation(value = "接口方法说明", notes = "@ApiOperation：用在请求的方法上，说明方法的用途、作用")
    @ApiImplicitParam(name = "name", value = "@ApiImplicitParams：用在请求的方法上，表示一组参数说明",required = true, dataType = "String", paramType = "path")
    public String swaggerGet( @PathVariable String name) {
        return "name="+name;
    }

    @PostMapping(value = "/swaggerPost")
    @ApiOperation(value = "新增用户", notes = "@ApiOperation Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
    public User swaggerGet(@RequestBody User user) {
        return user;
    }


    @GetMapping(value = "/swaggerApiParam")
    @ApiOperation(value = "测试参数")
    public User swaggerApiParam(@ApiParam(value = "主键查询" ,required = true) String id) {
        return new User();
    }

}

//////////////////////////////////////

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel("实体类 @ApiModel：用于响应类上（POJO实体类），描述一个返回响应数据的信息（描述POJO类请求或响应的实体说明）")
public class User implements Serializable {


    private static final long serialVersionUID = -6627165976923138391L;


    @ApiModelProperty(value = "用户名 @ApiModelProperty：用在POJO属性上，描述响应类的属性说明", dataType = "String", name = "username", example = "hughJin")
    private String username;
    @ApiModelProperty(value = "账户密码", dataType = "String", name = "password", example = "123456")
    private String password;


    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

集成knife4j

        <!--Knife4j-->
        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-springdoc-ui</artifactId>
            <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
            <version>3.0.2</version>
        </dependency>

集成后访问路径为：/doc.html#/home

集成后效果为：

swagger3项目源代码路径：

链接：https://pan.baidu.com/s/1YC6tKQmknaPJ0ESxbWjpbA
提取码：tidu