其他分享
首页 > 其他分享> > Spring Boot集成Springfox Swagger3和简单应用

Spring Boot集成Springfox Swagger3和简单应用

作者:互联网

摘要:Springfox Swagger可以动态生成 API 接口供前后端进行交互和在线调试接口,Spring Boot 框架是目前非常流行的微服务框架,所以,在Spring Boot 项目中集成Springfox非常有意义。介绍Spring Boot集成Springfox Swagger3及swagger的简单应用。

§前言

  Swagger是什么?官方说法:Swagger是一个规范和完整的框架,用于创建、描述、调试和可视化 RESTful 风格的 Web 服务。通俗地说,Swagger 是一个主要用来在线创建文档的插件,主要用来高质量地动态生成 API 接口供前后端进行交互和在线调试接口,如果不生成的话就需要写静态文档来交互,那样不仅速度慢而且不容易修改。发现了痛点就要寻找解决方案,故Swagger应运而生。

  Springfox Swagger是Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的源码自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的。Spring Boot 框架是目前非常流行的微服务框架,所以,在Spring Boot 项目中集成Springfox非常有意义,可以保证及时更新API文档,降低前后端沟通成本,提高系统迭代效率。

  本文所用软件开发环境如下:

  ♦ java version 13.0.1
  ♦ IntelliJ IDEA 2019.3.2 (Ultimate Edition)
  ♦ Spring Boot 2.3.1.RELEASE

§Spring Boot 集成 Springfox Swagger3

  若想为Spring Boot项目添加无需任何配置的springfox,需引入其maven依赖库:

        <!--集成 springfox swagger3 API-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

  为了便于管理API文档,建议编写一个Swagger配置类,这里的配置类如下:

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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger 配置类
 *
 * @author Wiener
 * @date 2021/2/26
 */
@EnableOpenApi
@Configuration
public class SwaggerConfig {
    //读取application.properties 文件设置的是否开启swagger属性,正式环境一般需要关闭
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
                // 是否开启swagger
                .enable(swaggerEnabled).select()
                // 过滤条件,扫描指定路径下的文件
                .apis(RequestHandlerSelectors.basePackage("com.eg.wiener.controller"))
                                //只保留/user/*风格的路径,大家可以调试一下
//                .paths(PathSelectors.ant("/user/*"))
                // 指定路径处理,PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot集成Springfox Swagger示例")
                .description("楼兰胡杨")
                // 开发者信息
                .contact(new Contact("楼兰胡杨", "https://www.cnblogs.com/east7/", "wienerXXX@163.com"))
                .version("1.0.0")
                .build();
    }
}

  注解@EnableOpenApi用于开启Swagger的自动配置,如果没加的话,自然而然也就看不到后面的swagger UI面板了。通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger UI面板;在 Docket 上添加筛选条件。Docket 类提供了 apis() 和 paths() 两个方法来帮助我们在不同级别上过滤接口:

  在上面的Swagger 配置类SwaggerConfig中,我们定义了 Docket 实例的 apis() 和 paths(),那么,swagger接口文档界面将只会展示包com.eg.wiener.controller中的API。关于PathSelectors.ant()的用法,各位同仁可以调试一下,由于时间有限,未曾验证是否可用。

  另一种解决方案就是使用@ApiIgnore注解屏蔽某些API。如果想在API文档中屏蔽掉某个接口,那么只需要在这个接口上加上@ApiIgnore 即可。

丰富文档内容

  在完成了上述配置后,已经算是初步集成Springfox Swagger3,可以启动服务查看API文档内容了。但是这样的文档主要针对请求本身,描述信息的主要来源是函数的命名,对用户并不友好,我们通常需要使用swagger注解增加一些说明文字来使得API文档内容更加丰满。Swagger中常用的注解及其说明:

@Api:用在类上,说明该类的作用。
@ApiOperation:为API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    l   code:数字,例如400
    l   message:信息,例如"必填参数不可为空"
    l   response:抛出异常的类   
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    l   @ApiModelProperty:描述一个model的属性

案例分析

  修改API实体类User,添加swagger注解:

@Setter
@Getter
@ToString
@ApiModel("用户实体")
public class User implements Serializable {

    private static final long serialVersionUID = -8842370047277749376L;
    @ApiModelProperty("用户 id")
    private Long id;
    @ApiModelProperty("用户姓名")
    private String userName;
    private Integer age;
    private String address;
    private String mobilePhone;
    private String remark;

    public User() {
    }
    public User(Long id, String userName, Integer age) {
        this.id = id;
        this.userName = userName;
        this.age = age;
    }
}

  在实体类使用注解@ApiModel和 @ApiModelProperty可以添加属性备注,这些备注信息将展示在swagger页面的Schema中,效果如下:

  在 controller 包下新建 UserController.java 类,通过在控制器类上增加 @Api 注解,可以给控制器添加标签信息。通过在接口方法上增加 @ApiOperation 注解来添加对接口的描述。关于swagger注解的更多信息,这里就不再阐述,需要的话,请去问问度娘。

/**
 * @author Wiener
 */
@RestController
@RequestMapping("/user")
@Api(tags="用户API")
public class UserController {

    private static Logger logger = LoggerFactory.getLogger(UserController.class);

    /**
     * 同时使用 @RequestBody 与 @RequestParam()
     * http://localhost:8087/wiener/user/addUser?token=IamToken
     * @param user
     * @param token
     * @return
     * @throws Exception
     */
    @PostMapping("/addUser")
    @ApiOperation(value="用户新增")
    public User addUser(@RequestBody User user, @RequestParam("token") String token) throws Exception {
        user.setRemark(token);
        return user;
    }
    /**
     * 示例地址 http://localhost:8087/wiener/user/getUser?id=9996669
     * @return
     * @throws Exception
     */
    @GetMapping("/getUser")
    @ApiOperation(value="用户查询(ID)")
    @ApiImplicitParam(name="id",value="查询ID",required=true)
    public User getUser(Long id) throws Exception {
        logger.info("--------------------");
        User user = new User();
        user.setId(id);
        user.setAddress("测试地址是 " + UUID.randomUUID().toString());
        logger.info("类信息: {}", user.getClass());
        return user;
    }
}

  这个时候已经算是进一步集成Springfox-Swagger3了,启动项目后访问http://IP:port/your-app-root/swagger-ui/index.html可以看到我们的swagger文档界面,其中,IP表示服务器IP地址,port表示项目配置的端口号,your-app-root表示项目配置的根路径。在我的项目中,其访问路径是http://127.0.0.1:8087/wiener/swagger-ui/index.html,在浏览器访问此URL进入如下文档界面:

使用 SwaggerUI访问API

  找到用户查询API getUser并进入接口详情页面,可以在详情页面右侧看到** Try it out** 按钮,单击此按钮即可进入接口调用界面,在id输入框随机输入一个Long类型的数字,单击执行即可请求getUser方法:

  从API返回值可以得出结论:使用 Swagger UI 成功访问了API,故集成集成Springfox Swagger3完毕。有底气甩了Postman了,你认为呢?

§小结

  Springfox既可以减少创建文档的工作量,同时接口文档又可以融合到代码之中去,使维护API文档和修改代码同步进行,让我们在修改代码逻辑的同时方便的修改文档说明,这太酷了。另外,Swagger UI界面页提供了强大的页面测试功能来调试每个RESTful API。欢迎点赞阅读,一同学习交流;若有疑问,请在文章下方留下你的神评妙论!

§Reference

标签:swagger,Spring,Boot,Swagger3,API,文档,user,Swagger
来源: https://www.cnblogs.com/east7/p/14454028.html