YApi——Swagger

Posted 2023-04-10 fxzm

YApi

YApi是高效、易用、功能强大的api管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护API，YApi还为用户提供了优秀的交互经验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

YApi让接口开发更简单高效，让接口的管理更具可读性、可维护性，让团队协作更合理

https://github.com/YMFE/yapi

要使用YApi，需要自己进行部署

 

Swagger

只需要按照Swagger的规范定义接口及接口相关的信息，再通过Swager衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。

https://swagger.io/

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

使用方式：

1、导入knife4j的maven坐标

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2、导入knife4j相关配置类(WebMvcConfig)

package com.itheima.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.itheima.common.JacksonObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

@Slf4j
@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig extends WebMvcConfigurationSupport 


    /**
     * 因为默认情况下只能访问到static和templates下的静态资源，index.html找不到
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) 
        /**
         * 设置静态资源映射
         */
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        log.info("开始静态资源映射");
    


    /**
     * 扩展mvc消息转换器
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) 
        log.info("扩展消息转换器");
        //创建消息转换器对象
        MappingJackson2HttpMessageConverter messageConverter = new MappingJackson2HttpMessageConverter();
        //设置对象转换器，底层使用Jackson将Java对象转为json
        messageConverter.setObjectMapper(new JacksonObjectMapper());
        //将上面的消息转换器对象追加到mvc框架的转换器集合中,0:放到集合最前面优先使用
        converters.add(0, messageConverter);
    
    
    private ApiInfo apiInfo()
        return new ApiInfoBuilder()
                .title("瑞吉外卖")
                .version("1.0")
                .description("瑞吉外卖接口文档")
                .build();
    
    @Bean
    public Docket createRestApi()
        //文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itheima.controller"))
                .paths(PathSelectors.any())
                .build();
    

 

3、设置静态资源，否则接口文档页面无法访问

/**
     * 因为默认情况下只能访问到static和templates下的静态资源，index.html找不到
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) 
        /**
         * 设置静态资源映射
         */
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        log.info("开始静态资源映射");
    

 

4在LoginCheckFilter中设置不再需要处理的请求路径

//定义不需要处理的请求路径
        String[] urls = new String[]
                "/employee/login",
                "/employee/logout",
                "/backend/**",
                "/front/**",
                "/common/**",
                "/user/sendMsg",//移动端发送短信
                "/user/login",//移动端登录
                "/doc.html",
                "/webjars/**",
                "/swagger-resources",
                "/v2/api-docs"
        ;

 

 启动项目，访问localhost:8080/doc.html。查看生成controller下的各种api文档，可以调试。

Swagger常用注解【目的：增加文档可读性】

注解　　　　　　　　　　　　说明

@Api　　　　　　　　　　　 用在请求的类上，例如Controller，表示对类的说明

@ApiModel　　　　　　　　  用在类上，通常是实体类，表示一个返回响应数据的信息

@ApiModelProperty　　　　　用在属性上，描述响应类的属性

@ApiOperation　　　　　　　用在请求的方法上，说明方法的用途、作用

@ApiImplicitParams　　　　　用在请求的方法上，表示一组参数说明

@ApiImplicitParam　　　　　  用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

 

YAPI:从0搭建API文档管理工具

参考技术A 最近在找一款API文档管理工具，之前有用过Swagger、API Manager、Confluence，现在用的还是Confluence。

我个人一直不喜欢用Swagger，感觉“代码即文档”，让代码里的文档无处不在，已经对代码造成了一定的入侵了。API Manager就是一个纯API文档管理的工具了。Confluence是万能的，也是最简单的，支持各种插件在线安装，可以有各种布局，支持MD文档，也支持表格、代码块等。

最近看到一篇文章在说YAPI，就准备搭建一个试试效果如何。

YAPI是去哪儿网开源的一款API管理工具，理念如下：

特性：

选择YAPI试试手的原因是因为我看到了它支持MockServer，这样前端开发同学就不用等待后端同学了。主要是我也懒得搭建一套mock服务，有这样一款工具何乐而不为呢？所以今天就找了一台服务器安装了一下。考虑排版问题，就以图片形式放出来了。

nodeJS长期支持版本官网下载地址：https://nodejs.org/dist/v10.16.0/node-v10.16.0-linux-x64.tar.xz，下载后执行如下命令：

nodeJS安装完毕。

YAPI安装，GitHub上已经有比较详细的文档了，地址：https://github.com/YMFE/yapi，这里说一下两种部署方式：

可视化部署：

yapi安装完毕，访问http://127.0.0.1:9090进行可视化配置一步一步往下走即可。

命令行部署（推荐方式）：

yapi安装完毕，访问http://127.0.0.1:config.json中配置的port即可访问。

node需要安装pm2模块，使用pm2模块后台运行yapi：

运行成功页面：

至此，YAPI就安装完毕了，简单实用一下还是不错的，因为是国产的，整体操作风格还是比较习惯的。在YAPI这里接口更改还有记录哦~

后面再慢慢体验这个里面的一些高级功能吧，比如MockServer、接口测试等功能。

大家还有什么更好用的API管理工具？你觉得一款优秀的API管理工具应该都有哪些必须的功能？欢迎推荐和讨论！