SpringCloud base-frame通用swagger搭建

最新推荐文章于 2024-08-08 17:13:07 发布

奔跑的闲鱼码农

最新推荐文章于 2024-08-08 17:13:07 发布

阅读量224

点赞数

分类专栏：【Java】- 框架文章标签： swagger2 通用swagger sc swagger

本文链接：https://blog.csdn.net/fly_west/article/details/122180812

版权

【Java】- 框架专栏收录该内容

5 篇文章 0 订阅

订阅专栏

背景

今天突然想给项目加丝袜哥，常规的集成百度一大片。于是乎就想写一个通用性很强的swagger，只需要在base-frame中写，一般每个公司的微服务引用都会引用公司自己的base-frame依赖。于是说干就干

实现

引入pom依赖

<!--swagger-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>

 <dependency>
     <groupId>org.projectlombok</groupId>
     <artifactId>lombok</artifactId>
     <version>1.16.22</version>
 </dependency>

注意,注意,注意

项目搭建的时候使用的spring-boot-starter-parent的版本为2.6及以上的，目前新建项目的时候从官网拉模板，拉下来版本就是2.6以上，项目启动的时候会报org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException这个错误，需要降低spring-boot-starter-parent的版本，我使用的是2.5.6

配置文件配置

server:
  port: 8081
swagger:
  title: demo_project
  description: project description
  version: 1.0
  contactEmail: 123456@qq.com

swagger配置文件实体

@Data
@Component
public class SwaggerVO {

    @Value("${swagger.title}")
    private String title;

    @Value("${swagger.description}")
    private String description;

    @Value("${swagger.version}")
    private String version;

    @Value("${swagger.contactEmail}")
    private String contactEmail;

    @Value("${server.port}")
    private String port;

}

自定义注解实现swagger，这样只需要在项目启动类上加上对应的注解就可以启用swagger。如果是手动打包那直接去掉注解就OK。但是如果是走CICD打包，我目前没有更好的解决方案，如果有方案的铁子看到欢迎留言，技术共勉！

自定义swagger启动注解

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@Documented
@Import({SwaggerConfig.class})
public @interface EnableSwagger {
}

注解实现类SwaggerConfig

@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private SwaggerVO vo;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(true)
                .select()
                //此处是扫描存在@Api注解的类，然后注入
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                    .build().globalOperationParameters(addParameter());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title(vo.getTitle())
                //文档描述
                .description(vo.getDescription())
                //服务条款URL
                .termsOfServiceUrl("http://localhost:"+vo.getPort() == null ? "8080" : vo.getPort() )
                //版本号
                .version(vo.getVersion())
                .build();
    }

    private List<Parameter> addParameter(){
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).defaultValue("xxxx").build();
        pars.add(tokenPar.build());
        return pars;
    }

}