时间戳

首页 > 技术文章 > spring boot 集成Swagger

spring boot 集成Swagger

huang580256 2021-04-15 23:31 原文

1，Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，后端集成下Swagger，然后就可以提供一个在线文档地址给前端

2，集成Swagger框架

1.导入pom依赖

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

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

这两个，一个用来生成接口文档(JSON 数据)，另一个用来展示将 JSON 可视化。

注：swagger2.x.x与swagger3.x.x区别：
在 3.0 版本中，不需要这么麻烦了，一个 starter 就可以搞定：

<dependency> 
    <groupid>io.springfox</groupid>
    <artifactid>springfox-boot-starter</artifactid>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一样，springfox-boot-starter 依赖可以实现零配置以及自动配置支持。也就是说，如果你没有其他特殊需求，加一个这个依赖就行了，接口文档就自动生成了。

接口地址

3.0 中的接口地址也和之前有所不同，以前在 2.9.2 中我们主要访问两个地址：

文档接口地址：http://localhost:8080/v2/api-docs
文档页面地址：http://localhost:8080/swagger-ui.html
现在在 3.0 中，这两个地址也发生了变化：

文档接口地址：http://localhost:8080/v3/api-docs
文档页面地址：http://localhost:8080/swagger-ui/index.html
特别是文档页面地址，如果用了 3.0，而去访问之前的页面，会报 404。

注解旧的注解还可以继续使用，不过在 3.0 中还提供了一些其他注解。
例如我们可以使用 @EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。

2.编写SwaggerConfig配置类，配置swagger信息

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
		.apiInfo(apiInfo())
		.enable(true)//enable是否启动swagger，如果为false，则不能在浏览器中启动
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("cam.example.controller"))
                //过滤路径
                //.paths("")
                .build();
    }

    //配置swagger信息==apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("Huang", "", "1764095439@qq.com");

        return  new ApiInfo(
                "Huang Api Documentation",
                "Huang Api 文档",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

3.测试，访问http://localhost:8080/swagger-ui.html
image

题：如何希望自己的swagger只在dev开发中使用，在pro生产环境中不使用？

  • 判断是不是开发环境 flag=true
  • 注入enable（flag）

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8081

application-pro.properties

server.port=8082

@Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles=Profiles.of("dev","test");

        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动swagger，如果为false，则不能在浏览器中启动
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("cam.example.controller"))
                //过滤路径
                //.paths("")
                .build();
    }

浏览器访问http://localhost:8081/swagger-ui.html (dev开发环境)：正常
访问http://localhost:8082/swagger-ui.html （pro生产环境）：访问不了

推荐阅读