# Swagger

**Repository Path**: bruce6213/swagger

## Basic Information

- **Project Name**: Swagger
- **Description**: Swagger Demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-04-01
- **Last Updated**: 2025-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 引言

- 用于快速生成接口文档。


- 实际开发时，直接使用**knife4j**，这个knife4j是java MVC架构集成Swagger生成API文档的**增强解决方案**；可以简单理解为是对Swagger的一层封装。


# 常用注解

![微信图片_20230401155749](https://gitee.com/bruce6213/image/raw/master/%E5%BE%AE%E4%BF%A1%E5%9B%BE%E7%89%87_20230401155749.png)

# 操作步骤

## 导入knife4j的maven坐标

```java
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>
    
    
// 后面需要用到@Data
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>
```

## 导入knife4j相关配置类

```java
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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
@EnableKnife4j
public class Swagger {

    @Bean
    public Docket defaultApi() {
         return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这里指定Controller扫描包路径, 注意无需包括实体类，只需接口类即可
                .apis(RequestHandlerSelectors.basePackage("com.jxsr.controller"))
                //这里指定扫描有ApiOperation注解的类
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //所有路径
                .paths(PathSelectors.any())
                //不包含^/inner/.*的路径
                //.paths(input -> !input.matches("^/inner/.*"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger Test")
                .description("构建RESTful APIs")
                .version("1.0")
                .build();
    }
}
```

## 配置文件

```
#swagger
knife4j:
  # 是否开启
  enable: true
  # 开启生产环境屏蔽
  production: true
  basic:
    # 是否开启认证
    enable: false 
    username: root
    password: root
```

## 访问页面

> http://localhost:8080/doc.html

**注：**

- 默认情况下，Swagger的UI页面通常可以通过/swagger-ui.html访问；而Knife4j一般是通过/doc.html访问，例如http://localhost:8080/doc.html
- 注意接口放行

## 接口文档导出

![image-20241211100053955](https://gitee.com/bruce6213/image/raw/master/image-20241211100053955.png)

# 可能会遇到的问题

## Failed to start bean ‘documentationPluginsBootstrapper’； nested exception is java.lang.NullPointerEx

[解决方法](https://blog.csdn.net/qq118034951/article/details/124622662)

## 响应参数不显示

[解决方法](https://www.cnblogs.com/ReturnOfTheKing/p/17278751.html )

# 参考文章

[API 注解](https://blog.csdn.net/HiBoyljw/article/details/81110553)