SpringBoot整合Swagger

官网：API Documentation & Design Tools for Teams | Swagger

swagger在项目当中承担的角色不多赘述，直接上代码

文中完整实例代码地址：java-technology: 日常学习的java技术

工程结构为：

1入门demo

1、创建maven项目

springboot-swagger

2、添加pom依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
​
    <groupId>com.nie</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.4.RELEASE</version>
        <relativePath/>
    </parent>
​
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger的两个核心依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger ui的两个核心依赖-->
        <!--swagger-ui.html-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--Swagger请求头添加header-->
        <!--doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.2</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

3、编写HelloController！

@Api(tags = "第一个swagger页面")
@RestController
@RequestMapping("/hello")
public class HelloController {
    @ApiOperation("第一个swagger方法")
    @GetMapping("/method1")
    public String test01(){
        return "method1";
    }
}

4、要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration
@EnableSwagger2 //Swagger配置对象
//链接url：http://localhost:8080/swagger-ui.html 固定格式
public class SwaggerConfig {
​
}

4编写启动类

@SpringBootApplication
// @EnableSwagger2
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

启动SpringBoot项目输入http://localhost:8080/swagger-ui.html或http://localhost:8080/doc.html，查看效果

2其他配置信息

列举了常用配置信息，

@Configuration
@EnableSwagger2 //Swagger配置对象
//链接url：http://localhost:8080/swagger-ui.html 固定格式
public class SwaggerConfig {
/*       @Bean//配置docket以配置Swagger具体参数
       //基本的swagger配置
       public Docket apiConfig(){
           return new Docket(DocumentationType.SWAGGER_2);
       }*/
    @Bean
    public Docket adminApiConfig(){
​
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")// 配置分组
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .apiInfo(adminApiInfoDesc())
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))//设置多个paths是为了分类管理路径，也可以对应到多个微服务上
                .build();
​
    }
    @Bean
    public Docket webApiConfig(){
​
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfoDesc())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
​
    }
    //文档描述
    //通过apiInfo()属性配置文档信息
    private ApiInfo adminApiInfoDesc(){
​
        return new ApiInfoBuilder()
                .title("网站后台管理系统-API文档")
                .description("本文档描述了后台系统接口")
                .version("1.0")
                .contact(new Contact("nzy", "http://baidu.com", "840599228@qq.com"))
                .build();
    }
    private ApiInfo webApiInfoDesc(){
​
        return new ApiInfoBuilder()
                .title("网站前台系统-API文档")
                .description("本文档描述了前台网站系统接口")
                .version("1.0")
                .contact(new Contact("nzy", "http://baidu.com", "840599228@qq.com"))
                .build();
    }
}

 

3常用注解

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

4扩展皮肤

默认访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

可以配置全局参数，配置全局token的时候可能会用到

 

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

参考文章为：狂神说SpringBoot14：集成Swagger终极版