Spring Boot——集成Swagger

万里顾一程
1,097 阅读4分钟

1、Swagger简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

出于安全和节省内存，在项目发布的时候，关闭swagger

Sawgger官网

2、SpringBoot集成Swagger

1、搭建环境

新建一个Springboot项目，导入web模块和swagger依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<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>

2、编写Swagger配置类

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {

}

测试http://localhost:8080/swagger-ui.html页面

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

启动程序，访问上面的页面： 在这里插入图片描述

3、配置Swagger信息

在Swagger的配置类里配置：

package com.cheng.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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {

    //配置了Swagger2的核心配置docket的bean实例，Docket:swagger的核心配置类
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)//指定api类型为swagger2
                .apiInfo(apiInfo());//配置swagger信息
    }
    //配置swagger信息 ApiInfo
    public ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("万里顾一程", "https://mp-new.csdn.net/", "3194525857@qq.com");

        return new ApiInfo("万里顾一程的SwaggerAPI文档"
                , "该文档由由万里顾一程创作，未经允许，不得转载，后果自负！"
                , "1.0"
                , "https://mp-new.csdn.net/"
                , contact
                , "Apache 2.0"
                , "https://mp-new.csdn.net/"
                , new ArrayList<VendorExtension>());
    }

}

启动程序，查看配置结果：配置成功，OK！

在这里插入图片描述

4、配置扫描接口及开关

配置接口

在Swagger的配置类里添加配置：

package com.cheng.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.ApiSelectorBuilder;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {

    //配置了Swagger2的核心配置docket的bean实例，Docket:swagger的核心配置类
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)//指定api类型为swagger2
                .apiInfo(apiInfo())//配置swagger信息
                .enable(true)//是否启动swagger，true启动  false关闭
                .select()
                /*RequestHandlerSelectors配置扫描接口的方式，方式如下：
                * basePackage指定要扫描的包 basePackage("com.cheng.controller")
                * any() 扫描所有包
                * none() 不扫描
                * withClassAnnotation() 扫描类上面的注解 withClassAnnotation(RestController.class)
                * withMethodAnnotation() 扫描方法上面的注解 withClassAnnotation(GetMapping.class)
                * */
                .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
                /*paths:根据路径扫描接口：
                * ant("/user/*")：指定要扫描的路径
                * any():扫描所有路径
                * none()：不扫描所有路径
                * regex()：扫描符合正则表达式的路径
                * */
                .paths(PathSelectors.any())
                .build();
    }
    //配置swagger信息 ApiInfo
    public ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("万里顾一程", "https://mp-new.csdn.net/", "3194525857@qq.com");

        return new ApiInfo("万里顾一程的SwaggerAPI文档"
                , "该文档由由万里顾一程创作，未经允许，不得转载，后果自负！"
                , "1.0"
                , "https://mp-new.csdn.net/"
                , contact
                , "Apache 2.0"
                , "https://mp-new.csdn.net/"
                , new ArrayList<VendorExtension>());
    }
}

配置开关

.enable(true)//是否启动swagger，true启动  false关闭

面试题：如何在开发环境中开启swagger，在发布环境中关闭swagger

建一个开发环境application-pro.properties

server.port=8081

建一个发布环境application-dev.properties

server.port=8082

在swagger配置里面进行配置：

@Bean
public Docket docket(Environment environment){

    //设置要使用的swagger环境,可以写多个
    Profiles of = Profiles.of("pro");

    //获取项目的环境
    boolean flag = environment.acceptsProfiles(of);

把flag放入enable()中

.enable(flag)

在配置文件中激活发布环境dev

spring-profiles-active=dev

启动程序访问Swagger-IU界面，成功访问！

然后在切换环境为开发环境pro

spring-profiles-active=pro

启动程序访问Swagger-IU界面，访问失败！

5、配置API文档的分组

.groupName("万里")

配置多个分组，通过多个Docket即可

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("神明");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("桃仙");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("墨尘");
}

测试：

在这里插入图片描述

6、接口注释

  • @API 使用在类上，表明是swagger资源，@API拥有两个属性:value、tags

  • @ApiOperation 使用于在方法上

  • @ApiParam

    使用在方法上或者参数上，字段说明

  • @ApiModel() 使用在类上，表示对类进行说明

  • @ApiModelProperty() 使用在方法，字段上，表示对model属性的说明

接口注释的使用

@ApiModel("User帮助文档")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("用户密码")
    public String pwd;
}

//返回值存在实体类，实体类就会被swagger扫描到
@ApiOperation("user的控制器")//给方法加注释
@GetMapping(value = "/user")
public User user(){
    return new User();
}

@ApiOperation("hello的控制器")
@GetMapping(value = "/hello")//@ApiParam("用户名")给参数加注释
public String hello(@ApiParam("用户名") String username){
    return username;
}
avatar
文章
阅读
粉丝