Laravel 安装 l5-swagger 扩展 让项目支持 Swagger

背景

用 Laravel 作为 API 支持框架,如果能够在写代码的过程,随便就把文档写了,那么是不是感觉很方便呢。

安装过程

当前操作默认在项目 根目录:

  1. 使用 composer 添加该包

    composer require darkaonline/l5-swagger
  2. 生成配置文件到 config 目录,可以自行去看看其中配置项

    php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
  3. 跑起来

php artisan serve
Laravel development server started: http://127.0.0.1:8000
  1. 浏览器访问

浏览器打开:http://127.0.0.1:8000/api/documentation

Laraver 搭建 Swagger UI 纯操作过程,献给一头雾水 + 四处碰壁的朋友

安装完毕


具体使用

刚接触它时候,我是拒绝的,总想用已知的东西来否认逃避去了解它,为什么不用 postman 呢?当出现这个想法的时候,我变成了 锤子,面对所有的问题 都把它 想成 钉子,咬牙看完 swagger 文档后,才知: 锤子+1

L5-Swagger 是什么?

是 laravel 的一个扩展包,结合 swagger-php + swagger-ui ,使我们能够在编写代码的时候,通过编写注释,生成 API 接口文档,并且可直接在开发的项目上直接访问这些 API 接口。

第一步:编写可生成API文档的注释

解析注释生成 API 文档的的功臣是 swagger-php,所以要安照它的使用方法来,它的 github 地址是:swagger-php 下面的内容假设在你已经了解了 swagger 的相关语法。

如:

<?php

/**
 * @SWG\Info(title="Test", version="0.0.1")
 */
// 别直接复制这里的注释,缩进破坏了,
// 请上 github 上复制它的用例。这里只作为演示作用

class MyController
{

/**
 * @SWG\Get(
 *     path="/api/syahi",
 *     @SWG\Response(response="200", description="An example resource")
 * )
 */
    public function say()
    {
        return ['msg' => 'Hello World'];
    }
    // Other Code...
}

注意 我用的版本是 swagger-php 2.x,所以注释使用的是 @SWG,现在最新版本使用的是 @OA做为标识(OpenApi 首字母)。

想了解更多,可以上 github,到该项目的演示项目参考其它注释方法:Examples

第二步:生成 API 文档

编写完上面的注释,运行此命名:

php artisan l5-swagger:generate

它会生成 API 文档,默认在项目根目录: storage\api-docs\api-docs.json,如:

Laraver 添加 Swagger 支持 纯操作过程,献给一头雾水 + 四处碰壁的朋友

第三步:浏览器访问

Laraver 添加 Swagger 支持 纯操作过程,献给一头雾水 + 四处碰壁的朋友

当然可以配置自动生成 API文档,请自行到 L5-Swagger 取经!

后话

  • 本文只是做一个入门的指引,解决最基本的问题:跑起来。
  • 本人是在接触 swagger 不到 24 小时内,要求项目中使用它,文章肯定有不足的地方,请各位谅解!
  • 现在接触下来,发现 swagger 很方便。
  • 见与你有缘,有一篇: 如何编写基于 Swagger-PHP 的 API 文档 能助你轻松掌握 swager-php!
本作品采用《CC 协议》,转载必须注明作者和本文链接
莫等闲,白了少年头,空悲切
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
讨论数量: 7

安装失败了

[root@VM_0_11_centos blog]# composer require darkaonline/l5-swagger
Do not run Composer as root/super user! See https://getcomposer.org/root for details
Using version ^6.0 for darkaonline/l5-swagger
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 5 installs, 0 updates, 0 removals
  - Installing symfony/yaml (v4.4.0):
 Failed, trying the next URL (0: proc_open(): fork failed - Cannot allocate memory)
Installation failed, reverting ./composer.json to its original content.
The following exception is caused by a lack of memory or swap, or not having swap configured
Check https://getcomposer.org/doc/articles/troubleshooting.md#proc-open-fork-failed-errors for details

PHP Warning:  proc_open(): fork failed - Cannot allocate memory in phar:///usr/local/bin/composer/vendor/symfony/console/Application.php on line 952

Warning: proc_open(): fork failed - Cannot allocate memory in phar:///usr/local/bin/composer/vendor/symfony/console/Application.php on line 952

  [ErrorException]
  proc_open(): fork failed - Cannot allocate memory

看文档https://getcomposer.org/doc/articles/troubleshooting.md#proc-open-fork-failed-errors 解决

/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
/sbin/mkswap /var/swap.1
/sbin/swapon /var/swap.1
4年前 评论
bigbug-gg (楼主) 4年前

头部的 accept 怎么设置

4年前 评论
bigbug-gg (楼主) 4年前

第一步,先定义个验证规则:

/**
*
* @SWG\SecurityScheme(
*     securityDefinition="Bearer",
*     type="apiKey",
*     in="header",
*     name="Authorization"
* )
*/

第二步,在需要使用这个验证的接口里面引入:

    /**
     * @SWG\Get(
     *      path="/common/sites",
     *      tags={"common"},
     *      summary="Get sites",
     *      security={
     *          {
     *              "Bearer":{}
     *          }
     *      },
     *      @SWG\Response(
     *         response=200,
     *         description="OK"
     *      )
     * )
     */

如图:

file

file

file

4年前 评论
故意 4年前

不太喜欢把接口文档写到注释里面,维护起来简直是灾难

4年前 评论
bigbug-gg (楼主) 4年前

file 看了官方文档,也看了你的,安装过程没问题,就是安装完访问/api/documentation报找不到js和css的错误,找不到问题出在哪,百度上也没有,laravel7.0,不知道你遇到过没,求帮助啊

3年前 评论
bigbug-gg (楼主) 3年前
loveMango 3年前

请问定义多个文档这个怎么设置

2年前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!
未填写
文章
36
粉丝
12
喜欢
75
收藏
67
排名:295
访问:3.2 万
私信
所有博文
社区赞助商