Swagger PHP使用指南

cnio 发布于2019-07-01 10:26 / 2127人阅读

摘要：，已经好了，试着访问根目录下，比如试试，出现界面就成功了没从先就用命令看下的路由最上面条就是刚刚添加的路由。

先说什么是Swagger, Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作.

官网: http://swagger.io/

参数文档: https://github.com/swagger-ap...

这东西咋用呢? 说白了就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件, 再通关Swagger前端来美化,整理JSON数据.

要使用Swagger要安装2个东西, 前段,用来显示;后端, 用来生成JSON

1, 安装前段

swagger-ui下载

1
git clone https://github.com/swagger-ap...
下载之后找到dist目录, 打开index.html把其中的那一串url改成自己的, 比如http://localhost/yii2/swagger...

$(function () {

  var url = window.location.search.match(/url=([^&]+)/);
  if (url && url.length > 1) {
    url = decodeURIComponent(url[1]);
  } else {
    url = "http://localhost/yii2/swagger-docs/swagger.json";
  }

还可以把界面调整成中文, 放开js文件的注释即可

1
2
3

然后打开URL就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用, 直接访问前端就好

http://localhost/yii2/swagger...

2, 安装后端

1
git clone https://github.com/zircote/sw...
因为我用的是yii2, 所以使用了composer来安装

"require": { "zircote/swagger-php": "*" }
之后composer update, 或者直接命令行, 详见https://github.com/zircote/sw...

DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php
我把swagger-php放在根目录下，然后用官方提供的Examples来生成测试json

cd swagger-php
mkdir doc
php swagger.phar Examples -o doc
"-o" 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. "-o" 后面是生成到哪个path

我没有进入到swagger-php下面, 直接打的命令行, 任意路径下都可以执行生成json操作

php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs
然后再看http://localhost/yii2/swagger... 生成了API文档

准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 参考官方文档http://zircote.com/swagger-ph...

比如Model的

/**

@SWGModel(

id="vps",

required="["type", "hostname"]",

@SWGProperty(name="hostname", type="string"),

@SWGProperty(name="label", type="string"),

@SWGProperty(name="type", type="string", enum="["vps", "dedicated"]")

)

*/
class HostVps extends Host implements ResourceInterface
{

// ...

}

比如Controller的

/**

@SWGResource(

basePath="http://skyapi.dev",

resourcePath="/vps",

@SWGApi(

path="/vps",

@SWGOperation(

method="GET",

type="array",

summary="Fetch vps lists",

nickname="vps/index",

@SWGParameter(

name="expand",

description="Models to expand",

paramType="query",

type="string",

defaultValue="vps,os_template"

)

*/
class VpsController extends Controller
{

 // ...

}

还看到一种集成把Swagger集成到Laravel中. Github地址是这个https://github.com/slampenny/...，不过这个就不能用git clone方式去按照了，配置太麻烦，用composer吧

composer require "jlapp/swaggervel:dev-master"
下一步 JlappSwaggervelSwaggervelServiceProvider 复制这一句到 app/config/app.php 的 providers数组最上面，然后

php artisan vender:publish
这一步把相关文件包括swagger ui复制到laravel框架public下面。OK，已经好了，试着访问根目录下，比如 www.1.com/api-docs试试，出现界面就成功了！没从先就用命令看下laravel的路由

php artisan route:list
最上面2条就是刚刚添加的路由。刷新页面是不是发现空白？要生产json需要你写@SWG的注释，再laravel的app目录下面任何文件写好就可以了，一般我们只需要写model和controller的，这个插件会扫描这个目录生产json文件。

=====================================

每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller, 先生成json再跳转到ui页面

$b2broot = Yii::getAlias("@b2broot");
$swagger = Swaggerscan($b2broot."/myapi");
$json_file = $b2broot."/swagger-docs/swagger.json";
$is_write = file_put_contents($json_file, $swagger);
if ($is_write == true) {
$this->redirect("http://localhost/yii2/swagger...");
}

参考自 https://www.cnblogs.com/derrc...

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/29166.html

Swagger 生成 PHP restful API 接口文档

摘要：需求和背景需求为客户端同事写接口文档的各位后端同学已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史我的故事却又不同因为首先来说我在公司是组负责人属于上述血泪史中催死人不偿命的客户端阵营但血泪史却是相通的没有自动化文档的日子对接口就是需求和背景需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史.我的故事却又不同,因为首先来说...

xiaotianyi 2019-06-28 18:43 评论0 收藏0
Swagger 生成 PHP API 接口文档

摘要：有同学推荐了，是一个简单但功能强大的表达工具。这里介绍使用生成文档的方法。将文档输出值的根目录下，可通过访问此文档。执行结果如图参考资料生成接口文档如何编写基于的文档使用生成文档不完全指南 Swagger 生成 PHP API 接口文档标签（空格分隔）： php 1、概况有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维...

miya 2019-07-01 10:51 评论0 收藏0
Lumen微服务生成Swagger文档

摘要：本文将会告诉你如何借助中插件，在开发微服务项目时项目和其它项目方法类似快速的在代码中使用注释来创建文档。本文将会持续修正和更新，最新内容请参考我的上的程序猿成长计划项目，欢迎，更多精彩内容请。框架配置我们使用当前最新的来演示。 showImg(https://segmentfault.com/img/remote/1460000017715535?w=1072&h=711); 作为一名...

alighters 2019-07-01 11:08 评论0 收藏0
swagger系列一：laravel中部署swagger ui

摘要：部署到项目中可以下来也可以下载文件。解压后把目录下的目录拷贝到下下的文件夹中，如新建。访问修改为自己的项目文件。找到，把修改为自己的，如，再次访问即可。但是并不存在，需要生成。如放在下的目录，用于存放文件。 1. 部署swagger ui 到项目中：可以Git下来 git clone https://github.com/swagger-api/swagger-uiv也可以下载zi...

lookSomeone 2019-06-28 18:39 评论0 收藏0
laravel使用手札——使用PHPStorm提升开发速度

摘要：安装支持和请移步到使用手札。在安装支持菜单栏搜索和安装使用时可不用完全参照插件的备注方式，使用自动补全内容的格式便可以，即建设的备注格式在自动补全小结从官方文档能看出对于支持可选和，经过试验后发觉必须安装才能很好地使用备注补全功能。 PHPStorm安装 PHPStorm 使用手札——安装看这里代码自动提示支持 laravel引入laravel-ide-helper能为PHPStor...

caozhijian 2019-07-01 12:14 评论0 收藏0