Swagger3学习笔记

参考https://blog.csdn.net/YXXXYX/article/details/124952856
https://blog.csdn.net/m0_53157173/article/details/119454044

引入依赖

 <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

启动类加注解@EnableWebMvc

不加会报错

@SpringBootApplication
@EnableWebMvc
public class SwaggerApplication {
    
    

    public static void main(String[] args) {
    
    
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

控制器

@RestController
@RequestMapping("/user")
public class UserController {
    
    
    @GetMapping("get")
    public String getUser() {
    
    
        return "user";
    }
}

配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    
    }

启动

访问http://localhost:8080/swagger-ui/index.html

配置Swagger 的文档生成规则

Docket 是一个配置类，用于配置 Swagger 的文档生成规则。通过创建一个 Docket 实例，您可以指定要生成的文档的详细信息，例如 API 的基本信息、路径规则、请求参数、响应信息等。

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    
    

    @Bean
    public Docket docket(Environment environment) {
    
    
        Profiles profiles = Profiles.of("dev", "test"); // 设置要显示swagger的环境
        boolean isOpen = environment.acceptsProfiles(profiles); // 判断当前是否处于该环境

        return new Docket(DocumentationType.OAS_30)
                // 文档信息配置
                .apiInfo(apiInfo())
                // 设置是否启动Swagger，通过当前环境进行判断：isOpen
                .enable(isOpen)
                // 配置扫描的接口
//                .select()
                // 配置扫描哪里的接口
//                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
//                // 过滤请求，只扫描请求以/category开头的接口
//                .paths(PathSelectors.ant("/user/**"))
//                .build()
                ;
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("外卖项目接口文档") // 文档标题
                .description("基本的一些接口说明") // 文档基本描述
                .contact(new Contact("xxxx", "https://blog.csdn.net", "[email protected]")) // 联系人信息
                .termsOfServiceUrl("http://terms.service.url/组织链接") // 组织链接
                .version("1.0") // 版本
                .license("Apache 2.0 许可") // 许可
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0") // 许可链接
                .extensions(new ArrayList<>()) // 拓展
                .build();
    }

}

spring:
  profiles:
    active: dev

在开发中有开发环境、测试环境、发布环境，Swagger文档不应该在有些环境中出现，就比如发布环境，不仅占内存，而且接口信息还容易泄露出去；

使用public Docket enable(boolean externallyConfiguredFlag)方法，看看是否启用swagger

整合knife4j

去除下面原先swagger依赖

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

加入

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

去除@EnableOpenApi，换成@EnableKnife4j，配置本地资源映射路径，佛足额访问不了Knife4j首页

@EnableKnife4j//启用knife4j
@Configuration
//@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {
    
    

    /**
     * 不配置这个访问不了knife4j首页
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

访问http://localhost:8080/doc.html

上传文件

使用@RequestPart(“file”)注解，不然不会展示上传文件按钮

    @PostMapping(value = "/upload")
    @ApiOperation("上传")
    public String upload(@RequestPart("file") MultipartFile file) {
    
    
        return "上传成功";
    }

解决返回乱码问题

/**
 * 中文乱码解决
 */
@Configuration
public class CharsetConfig implements WebMvcConfigurer {
    
    

    @Bean
    public HttpMessageConverter<String> responseBodyConverter() {
    
    
        return new StringHttpMessageConverter(StandardCharsets.UTF_8);
    }

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    
    
        converters.add(responseBodyConverter());
    }

}