Springboot 集成swagger3

Springboot 集成swagger3

1.引入springboot、swagger依赖

 <parent>
        <artifactId>spring-boot-dependencies</artifactId>
        <groupId>org.springframework.boot</groupId>
        <version>2.3.9.RELEASE</version>
  </parent>
  <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
      <!--LomBok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
      
      <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.7.18</version>
       </dependency>
      <!-- swagger3-->
        <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>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>swagger-annotations</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>guava</artifactId>
                    <groupId>com.google.guava</groupId>
                </exclusion>
            </exclusions>
        </dependency>
      
     </dependencies>

2.swagger 启动配置

import cn.hutool.core.net.NetUtil;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

import java.util.Set;

@Slf4j
@Component
public class StartUtil {

    private final ApplicationContext applicationContext;

    public StartUtil(ApplicationContext applicationContext) {
        this.applicationContext = applicationContext;
    }

    public void logStartInfo() {

        // 打印启动信息
        String serverPort = applicationContext.getEnvironment().getProperty("server.port", "8080");
        String serverPath = applicationContext.getEnvironment().getProperty("server.servlet.context-path", "");

        Set<String> set = NetUtil.localIpv4s();
        String localIp = NetUtil.LOCAL_IP;
        for (String s : set) {
            // 不使用本机地址，也不使用本机网关地址
            if (!localIp.equals(s) && !s.endsWith(".1")) {
                localIp = s;
                break;
            }
        }
        String apiUrl = String.format("http://%s:%s%s", localIp, serverPort, serverPath);

        log.info("application swagger started at    {}/doc.html#plus", apiUrl);
        log.info("application start successful!");

        /*
         * 注册shutdown钩子，当应用程序正常关闭时，会调用这里的方法
         * kill -9时，不会触发这段代码
         */
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            log.info("stop application successfully");
        }));
    }
}

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

import java.nio.charset.StandardCharsets;

/**
 * Swagger配置
 * @author 
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("swagger").description("swagger").version("1.0.0").build();
    }

    /**
     * 项目中配置从pom中读取swagger配置
     * spring读取配置文件默认采用ISO8895编码，但pom中为UTF8编码，使用此方法进行转换
     */
    private String convert(String text) {
        return new String(text.getBytes(StandardCharsets.ISO_8859_1), StandardCharsets.UTF_8);
    }
}

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class StartRunner implements ApplicationRunner {
    private final StartUtil startUtil;


    public StartRunner(StartUtil startUtil) {
        this.startUtil = startUtil;
    }

    @Override
    public void run(ApplicationArguments args) {
        startUtil.logStartInfo();
    }

}

3.swagger注解

1）启动类中添加 @EnableOpenApi 注解

2）controller 添加 @Api(tags=“接口分类名称”)注解

3）接口上添加 @ApiOperation(“接口名称”) 注解

3）请求响应参数添加 @Schema(name = “字段名”, description = “字段描述”)

启动后的ui界面