Swagger学习使用

news2024/11/16 13:38:31

swagger升级导致访问ui页面地址不一样

方式一

依赖

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.3.RELEASE</version>
 </parent>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

启用Swagger2

@EnableSwagger2
@SpringBootApplication
public class AmisProjectApplication extends SpringBootServletInitializer{

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

    //使用外部tomcat启动项目要重写该方法
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(AmisProjectApplication.class);
    }
}

定义Swagger配置类

package com.xysd.amisproject;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createApiDocket() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.parameterType("header")//参数类型支持header, cookie, body, query etc
                .name("access_token")//参数名
                .defaultValue("")//默认值
                .description("令牌")//描述信息
                .modelRef(new ModelRef("string"))//指定参数值的类型
                .required(false)//非必需，这里是全局配置
                .build();
        pars.add(tokenPar.build());
        //根据配置文件项 swagger是否启用，禁用
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(pars)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xysd.amisproject"))
                .paths(PathSelectors.ant("/api/**"))
                .build().groupName("对外API接口文档");

    }

    @Bean
    public Docket create_ApiDocket() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.parameterType("header")//参数类型支持header, cookie, body, query etc
                .name("access_token")//参数名
                .defaultValue("")//默认值
                .description("令牌")//描述信息
                .modelRef(new ModelRef("string"))//指定参数值的类型
                .required(false)//非必需，这里是全局配置
                .build();
        pars.add(tokenPar.build());
        //根据配置文件项 swagger是否启用，禁用
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(pars)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xysd.amisproject"))
                .paths(PathSelectors.ant("/_api/**"))
                .build().groupName("对内API接口文档");

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("AMIS-PROJECT")
                .description("AMIS-PROJECT接口文档")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

测试

启动本地服务
访问地址
http://localhost:8000/amis-project/swagger-ui.html

效果图

在这里插入图片描述

方式二

依赖

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

启用Swagger2


@EnableSwagger2
@SpringBootApplication
public class AmisProjectApplication extends SpringBootServletInitializer{

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

    //使用外部tomcat启动项目要重写该方法
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(AmisProjectApplication.class);
    }
}

定义配置类

package com.xysd.bizbase.resources;

import java.util.ArrayList;
import java.util.List;

import org.springframework.beans.factory.annotation.Value;
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.builders.RequestParameterBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    
    @Value("${swagger.sysName:''}")
    private String swaggerSysName;
    
    @Bean
    public Docket createApiDocket() {
        List<RequestParameter> pars = new ArrayList<RequestParameter>();
        RequestParameterBuilder tokenPar = new RequestParameterBuilder();
        tokenPar.in(ParameterType.HEADER)//参数类型支持header, cookie, body, query etc
                .name("access_token")//参数名
                .description("令牌")//描述信息
                .required(false)//非必需，这里是全局配置
                //.query(sb -> sb.defaultValue("1").allowEmptyValue(true)) //指定默认值 指定是否必填
                ;
        pars.add(tokenPar.build());
        
        return new Docket(DocumentationType.OAS_30)
                .globalRequestParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xysd"))
                .paths(PathSelectors.ant("/*/api/**").or(path -> path.contains("login")))
                .build()
                .groupName("对外API接口文档")
                ;
                
    }
    
    @Bean
    public Docket createRestDocket() {
        List<RequestParameter> pars = new ArrayList<RequestParameter>();
        RequestParameterBuilder tokenPar = new RequestParameterBuilder();
        tokenPar.in(ParameterType.HEADER)//参数类型支持header, cookie, body, query etc
                .name("access_token")//参数名
                .description("令牌")//描述信息
                .required(false)//非必需，这里是全局配置
                //.query(sb -> sb.defaultValue("1").allowEmptyValue(true)) //指定默认值 指定是否必填
                ;
        pars.add(tokenPar.build());
        
        return new Docket(DocumentationType.OAS_30)
                .globalRequestParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xysd"))
                .paths(PathSelectors.ant("/*/rest/**").or(path -> path.contains("login")))
                .build()
                .groupName("对外REST接口文档")
                ;
                
    }
    
    @Bean
    public Docket create_ApiDocket() {
        List<RequestParameter> pars = new ArrayList<RequestParameter>();
        RequestParameterBuilder tokenPar = null;
        
        tokenPar = new RequestParameterBuilder();
        tokenPar.in(ParameterType.HEADER)//参数类型支持header, cookie, body, query etc
                .name("access_token")//参数名
                .description("访问令牌")//描述信息
                .required(false)//非必需，这里是全局配置
                //.query(sb -> sb.defaultValue("1").allowEmptyValue(true)) //指定默认值 指定是否必填
                ;
        pars.add(tokenPar.build());
        
        tokenPar = new RequestParameterBuilder();
        tokenPar.in(ParameterType.HEADER)//参数类型支持header, cookie, body, query etc
                .name("inner_token")//参数名
                .description("内部令牌")//描述信息
                .required(false)//非必需，这里是全局配置
                //.query(sb -> sb.defaultValue("1").allowEmptyValue(true)) //指定默认值 指定是否必填
                ;
        pars.add(tokenPar.build());
        
        return new Docket(DocumentationType.OAS_30)
                .globalRequestParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xysd"))
                .paths(PathSelectors.ant("/*/_api/**"))
                .build()
                .groupName("对内_API接口文档")
                ;
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(swaggerSysName+"接口文档")
                .description(swaggerSysName+"接口文档")
                //.termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
    
}