springboot配置swagger示例

swagger2配置

一、Swagger的作用是什么？

1、接口的文档在线自动生成。

2、 接口功能测试。

注意：

 引入依赖(这里要注意springboot项目整合swagger要注意两者的版本不能相差太多，springboot项目的版本低，swagger版本不能太高，反之亦然，避免项目报错)

 本利使用的springboot版本为：2.1.3.RELEASE ~~~ 2.5.7

                      swagger版本为：2.9.2

二、使用步骤

idea新建springboot项目

springboot 版本为2.5.7

    
        org.springframework.boot
        spring-boot-starter-parent
        2.5.6
         
    

pom.xml配置swagger

需要注意springboot 的版本与swagger配合问题；这里使用的swagger版本为2.9.2

 
        
            io.springfox
            springfox-swagger2
            2.9.2
        

        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

配置类文件

别忘记添加注解@Configuration @EnableSwagger2

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;


/**
 * Swagger配置类，该类里面的应该是固定的，主要用来设置文档的主题信息，比如文档的大标题，副标题，公司名
 */
@Configuration//托管spring
@EnableSwagger2//开启swagger功能
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        //版本类型是swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                //通过调用自定义方法apiInfo，获得文档的主要信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))//扫描该包下面的API注解
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2 构建RESTful APIS") //接口管理文档首页显示
                .description("Swagger使用演示")//API的描述
                // .termsOfServiceUrl("www.footmark.top")//网站url等
                .version("1.0")
                .build();
    }
}

新建Controler类测试

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController; 
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

/* 类注解 */
@Api(value = "用户管理", description = "", tags = {"用户管理"})
@RestController
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "desc of method", notes = "ddddd")
    @GetMapping(value="/hello")
    public String hello() {
        return "Hello dddd!";
    }
}

测试地址

http://访问地址/swagger-ui.html

swagger3配置

pom.xml

        
        
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

SwaggerConfig配置类

import io.swagger.annotations.ApiOperation;
import org.springframework.boot.SpringBootConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@SpringBootConfiguration
@EnableOpenApi
public class SwaggerConfig {
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(false) // ture 启用Swagger3.0， false 禁用（生产环境要禁用）
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  // 扫描的路径使用@Api的controller
                .paths(PathSelectors.any()) // 指定路径处理PathSelectors.any()代表所有的路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxx接口文档")
                .description("xxxx接口文档")
                .contact(new Contact("jeffcail", "https://blog.caixiaoxin.cn/", "[email protected]"))
                .version("1.0")
                .build();
    }
}

http://地址:端口/swagger-ui/index.html

Swagger笔记—Swagger3详细配置_zhang641692786的博客-CSDN博客_swagger3 配置