API Document Auto Generator

20 篇文章 0 订阅

Swagger

生态

在这里插入图片描述

接入Swagger

# 添加依赖
  <swagger.version>2.9.2</swagger.version>

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${swagger.version}</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>${swagger.version}</version>
  </dependency>
        
# 配置参数

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled:true}")
    private boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {

        /**
         * basePackage填你要生成的接口的包
         * 不想暴露的接口可以在该API上加注解@ApiIgnore
         */
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnabled)
                .apiInfo(apiInfo())
                // 禁用默认的response
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 信息
     *
     * @return
     */
    private ApiInfo apiInfo() {

        String desc = PrintUtil.format("生成时间:{}", new Date());
        return new ApiInfoBuilder().title("[demo] Service Api Documentation")
                .description(desc).version("1.1").build();
    }
}

参数配置详解:
https://springfox.github.io/springfox/docs/current/#quick-start-guides

启动项目
访问 http://{ip}:{port}/swagger-ui.html 预览界面

在这里插入图片描述

注解
常用注解自己上网搜吧

禁用默认接口返回状态
是否使用默认的接口返回状态
code 201
code 401
code 403
code 404

配置中已给出
useDefaultResponseMessages(false)

禁用Swagger
生产环境禁用swagger
通过配置环境变量 swagger.enabled 在参数配置类中决定是否启动swagger
.enable(swaggerEnabled)

接口测试
点击“Try it out ”,可进行接口测试

利弊分析

  • 优点
    接入简单
    功能丰富
    接口分类
    mock测试

  • 缺点
    界面不够直观
    不支持多项目
    一定的注释成本

界面改进

一位前端牛人写的 swagger-ui-layer ,重新排了下版,好看多了
项目已开源
Online demo
http://suldemo.tianox.com/docs.html

# 添加依赖
   <dependency>
       <groupId>com.github.caspar-chen</groupId>
       <artifactId>swagger-ui-layer</artifactId>
       <version>1.1.1</version>
   </dependency>

启动项目,访问 http://{ip}:{port}/docs.html 预览界面
在这里插入图片描述

接口测试
点击“Debug”,可进行接口测试

优缺点分析

  • 优点

简单直观
交互友好
接口测试

  • 缺点

需添加额外注解
无历史版本维护
文档生成要依赖于接口对象定义完成

  • 改造建议
    接口搜索
    分组过滤
    多项目支持
    历史版本存储

Java Doc

查看帮助

# 查看帮助命令
javadoc -help

牛刀小试

  • 生成接口文档
    javadoc -d /Users/yuan/Desktop/company/doc -sourcepath /Users/yuan/try/demo/src/main/java/com/example/demo/**/*.java -subpackages /Users/yuan/try/demo/src/main/java/com/example/demo/

  • 查看文档
    预览界面
    在这里插入图片描述

优缺点分析

优点

注释即文档
规范代码编写(参照学习 jdk 源码)
类信息详尽
目录层次分明
支持导出

缺点

接口信息不直观
关注点不突出
不支持多项目
不支持mock测试
文档生成要依赖于开发工作的完成

Furthermore

  • 在线编辑
  • 接口搜索
  • 多项目集成
  • 多分支切换
  • 历史版本维护

Reference

https://blog.csdn.net/tuposky/article/details/77965139
https://www.oschina.net/p/swagger-ui-layer

  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
fastapi-mysql-generator 是一个用于快速生成FastAPI和MySQL的框架的工具。FastAPI是一个现代、快速(高性能)的web框架,而MySQL是一个流行的关系型数据库。 使用 fastapi-mysql-generator,可以从一个简单的命令行界面中生成 FastAPI 应用程序,并与 MySQL 数据库集成。这个工具可以自动创建数据库表和模型(Model),并提供一组 API 端点,用于执行常见的 CRUD(创建、读取、更新和删除)操作。 fastapi-mysql-generator 的主要优势之一是它的简单易用性。无论是初学者还是有经验的开发人员,都可以快速上手并生成一个完整的基于FastAPI和MySQL的应用程序。只需要几个简单的步骤,就可以生成项目的基本结构和代码。同时,fastapi-mysql-generator 还提供了一些配置选项,可以根据需求进行自定义设置,以满足特定的应用程序需求。 这个工具还提供了一些有用的特性,以增强开发的效率和便利性。例如,它可以自动生成 API 文档,包括请求和响应模型的文档说明。此外,fastapi-mysql-generator 还支持身份验证和授权功能,以确保 API 路由的安全性。 总而言之,fastapi-mysql-generator 是一个快速生成 FastAPI 和 MySQL 应用程序的方便工具。它简化了应用程序的开发过程,并提供了一些有用的特性,以提高开发效率和便利性。无论是初学者还是有经验的开发人员,都可以受益于这个工具的使用。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值