0
点赞
收藏
分享

微信扫一扫

写一个thinkphp SwaggerV3 扩展包


写一个thinkphp SwaggerV3 扩展包_Laravel

文章目录

  • ​​创建包​​
  • ​​添加swagger​​
  • ​​本地导入composer​​
  • ​​创建控制器​​
  • ​​添加路由​​
  • ​​添加Swagger-ui​​
  • ​​静态资源导入​​
  • ​​UI 报错隐藏​​
  • ​​一些感想​​

大致过程和我之前写的Laravel 扩展差不多 ​​Laravel 写一个中文验证扩展包​​只有一些小小的区别这边写个教程。希望为thinkphp 开发者做一点点贡献。
主要讲一些开发的过程和一些❤感悟吧,对Tp不是特别熟,欢迎大家指正(づ ̄3 ̄)づ╭❤~

源码:​​https://github.com/liaoshengping/think-swagger​​

安装:

composer require liaosp/think-swagger -vvv

创建包

🌰这边以Swagger 添加到Tp为例子

我在tp的根目录下创建pkg

mkdir pkg
cd pkg
package-builder build think-swagger

添加 zircote/swagger-php,在composer.json 添加

添加swagger

"require": {
"zircote/swagger-php": "^3.2"
},

根据 ​​官网​​的示例,我们希望在TP触发如下代码

<?php
require("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

本地导入composer

需要在tp的compsoer 加入 “minimum-stability”: “dev”

"minimum-stability": "dev"

repositories 加入

{
"type": "path",
"url": "pkg\\think-swagger"
}

创建控制器

在src 创建 一个Controller.php

一个是展示 html 的,一个是提供swagger api 接口的

具体代码可查阅:

​​https://github.com/liaoshengping/think-swagger/blob/master/src/Controller.php​​

添加路由

"autoload": {
"psr-4": {
"Liaosp\\ThinkSwagger\\": "src"
},
"files": [
"src/route.php"
]
},

添加router.php

tp5 我现在的版本可以这样做,但是TP6我试了下,不行啊报错;如果后面有Tp6项目了,我会把tp6部分整合一下欢迎大家收藏。

Route::any('apidoc', '\\Liaosp\\ThinkSwagger\\Controller@apidoc');
Route::any('apidocJson', '\\Liaosp\\ThinkSwagger\\Controller@apidocJson');

添加Swagger-ui

swagger ui 是 开源的 js库 ​​https://github.com/swagger-api/swagger-ui​​

静态形式引用 dist/index.html

静态资源导入

Swagger 主要需要这三个文件

'/swagger/swagger-ui.css',
'/swagger/swagger-ui-bundle.js',
'/swagger/swagger-ui-standalone-preset.js'

tp5没有publish ,所以我想了一个办法,通过查询是否存在资源,进行资源的发布。感兴趣的可以看下上面提供的源码

UI 报错隐藏

Swagger-UI默认会将你的接口JSON传给swagger.io进行格式验证,然后对于我们已经使用了swagger-php的项目来说基本不需要(因为写错了Annotation的话会造成Swagger JSON接口报错),而且内部项目有时也不方便暴露,所以我们可以关闭验证功能来去除右下角的ERROR提示图标。这个配置并不存在于swagger-ui/index.html中,我们需要手动在Swagger UI声明时设置一个新参数:

window.swaggerUi = new SwaggerUi({
// ...

validatorUrl: null, //添加这个配置
});

一些感想

可能我的思维Laravel化了,在开发之前我认为一些 本应该有的扩展功能都应该有的,但是我查阅了好几个作者的think-swagger扩展包,不太灵活了。以至于有一些开发扩展包的同学,需要手动改源码,或者干脆就没有composer 包,直接写教程如何去实现。

接着我查阅了下Tp6的源码,在开发扩展方面有一定的增强,比如下面的是我学Tp6 的官方的插件:

Laravel 的包的提供者的命名官方的是在包名加 Provider

我查阅了下tp的扩展包,习惯于用Service 作为包的提供者


"extra": {
"think": {
"services": [
"Liaosp\\ThinkSwagger\\Service"
]
}
}

不过Laravel 之前也需要手动添加Provider,希望国产Tp越来越好,后面再看看有没有接触TP6再把Swagger 升级一下吧。


举报

相关推荐

0 条评论