此种方法,不用每个项目都安装zircote/swagger-php,我觉得还是挺好的
1、全局安装zircote/swagger-php
composer global require zircote/swagger-php
2、配置环境变量(openapi路径)
export PATH="~/.composer/vendor/bin:${PATH}"
source ~/.bash_profile
3、随便找个目录下的php文件添加title信息
/**
* @OA\Info(title="health app API", version="2.0")
*/
4、生成yaml文件
打开终端运行openapi
JianLongs-MBP:~ jianlongnie$ openapi
Error: Specify at least one path.
Usage: openapi [--option value] [/path/to/project ...]
Options:
--output (-o) Path to store the generated documentation.
ex: --output openapi.yaml
--exclude (-e) Exclude path(s).
ex: --exclude vendor,library/Zend
--pattern (-n) Pattern of files to scan.
ex: --pattern "*.php" or --pattern "/\.(phps|php)$/"
--bootstrap (-b) Bootstrap a php file for defining constants, etc.
ex: --bootstrap config/constants.php
--processor Register an additional processor.
--format Force yaml or json.
--debug Show additional error information.
--help (-h) Display this help message.
进入项目根目录,运行:
openapi --output openapi.yaml app/api
生成的openyaml文件已经在项目根目录下面,
image.png
5、配置swagger-ui,到这里我们已经生成了yaml文件,下一步就是如何显示的问题了,下载swagger-ui,
image.png
下载完成之后,把这个文件件放到nginx或者apache服务器下面,打开里面的index.html修改yaml文件路径
image.png
改为上一步我们生成好的yaml路径,然后访问服务器下面的index.html即可,像我的是
http://localhost:84/public/swagger-ui/index.html
注释方面的例子:
/**
* @OA\Post(
* path="/Register/mobile",
* summary="用户手机号注册",
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="mobile",
* type="string"
* ),
* @OA\Property(
* property="password",
* type="string"
* ),
* @OA\Property(
* property="code",
* type="string",
* description="验证码"
* ),
* @OA\Property(
* property="key",
* type="string",
* description="验证码key"
* ),
* example={"key":"register_mobile_code_78b48c4eb0b5c0a87522e89257b79c38","mobile": "+12103841215", "password": "NJLd123456","code":"1111"}
* )
* )
* ),
* @OA\Response(
* response=200,
* description="OK"
* )
* )
*/