Swagger 生成 PHP API 接口文档

Swagger 生成 PHP API 接口文档

标签(空格分隔): php


1、概况

有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用。

有同学推荐了swagger+easymock,Swagger是一个简单但功能强大的API表达工具。 这里介绍使用swagger-php生成PHP API文档的方法。

2、安装与使用

2.1 安装swagger-php包

git clone https://github.com/zircote/swagger-php.git

composer install
// 全局的
composer global require zircote/swagger-php

// 项目中
composer global require zircote/swagger-php

2.2 laravel项目安装

使用 L5 Swagger https://github.com/DarkaOnLine/L5-Swagger

具体安装过程请参考此文档: https://github.com/DarkaOnLin...

2.3 编写API注解

# 创建文件 demo/customer.php
<?php

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class Customer
{
    /**
     * @OA\Get(
     *     path="/customer/info",
     *     summary="用户的个人信息",
     *     description="这不是个api接口,这个返回一个页面",
     *     @OA\Parameter(name="userId", in="query", @OA\Schema(type="string"), required=true, description="用户ID"),
     *     @OA\Response(
     *      response="200",
     *      description="An example resource"
     *     )
     * )
     */
    public function info(int $userId, string $userToken)
    {

    }
}

2.4 生成swagger API 文件

./swagger-php/bin/openapi demo -o ./docs

API 内容如下:

# docs/openapi.yaml
openapi: 3.0.0
info:
  title: 'My First API'
  version: '0.1'
paths:
  /customer/info:
    get:
      summary: 用户的个人信息
      description: '这不是个api接口,这个返回一个页面'
      operationId: 'Customer::info'
      parameters:
        -
          name: userId
          in: query
          description: 用户ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'An example resource'

3、展示

git clone https://github.com/swagger-api/swagger-ui.git

composer install

直接通过Dockerfile构建、启动项目, 或者使用docker-compose进行服务管理。

version: '2'

services:
    swagger-ui:
      build: .
      ports:
        - "8080:8080"
      volumes:
        - ./dist/:/usr/share/nginx/html/
      restart: on-failure

访问 http://localhost:8080/ 即可到 swagger 编辑器预览界面。

./swagger-php/bin/openapi demo -o ./swagger-ui/dist/

将 api文档输出值swagger ui的根目录下,可通过 http://localhost:8080/openapi.yaml 访问此api文档。

执行 Explore 结果如图:

image

4、参考资料


行易难
我很幸运, 正在做自己喜欢做的事儿, 喜欢自己喜欢的人。
1 篇内容引用

行易难

513 声望
36 粉丝
0 条评论
推荐阅读
好久不见
好久不见! 博客好久不更新了,先整理下之前的文章,2020年加油。 历史博文: 使用swoole改造laravel应用 memcached分布式原理与实现 Sessions共享技术设计 字符串查找算法及原理 深入理解PHP之isset和array_key_...

蒋建勇2阅读 2.5k

怎样用 PHP 来实现枚举?
在数学和计算机科学理论中,一个集的枚举是列出某些有穷序列集的所有成员的程序,或者是一种特定类型对象的计数。这两种类型经常(但不总是)重叠。枚举是一个被命名的整型常数的集合,枚举在日常生活中很常见,...

唯一丶25阅读 6.3k评论 4

图片防盗链破解 解决图片防盗链问题 反向代理
当客户端(浏览器)向服务器请求内容的时候,会提交一个header,这个header中包含了如:浏览器信息、cookie等内容,那么有一个叫referer的东东,也包含在这里面。

TANKING7阅读 11.2k评论 5

Git操作不规范,战友提刀来相见!
年终奖都没了,还要扣我绩效,门都没有,哈哈。这波骚Git操作我也是第一次用,担心闪了腰,所以不仅做了备份,也做了笔记,分享给大家。问题描述小A和我在同时开发一个功能模块,他在优化之前的代码逻辑,我在开...

王中阳Go5阅读 2k评论 2

封面图
PHP转Go实践:xjson解析神器「开源工具集」
我和劲仔都是PHP转Go,身边越来越多做PHP的朋友也逐渐在用Go进行重构,重构过程中,会发现php的json解析操作(系列化与反序列化)是真的香,弱类型语言的各种隐式类型转换,很大程度的减低了程序的复杂度。

王中阳Go4阅读 1.3k评论 2

封面图
微信公众号开发:自动回复文本/图片/图文消息/关键词回复/上传素材/自定义菜单
对接流程1、申请微信公众号测试账号URL:[链接]2、登录,配置开发者服务器URL和Token开发者服务器配置代码:config.php {代码...} URL是config.php在你服务器的URLToken是上面代码自己设置的Token搞定之后,就能完...

TANKING2阅读 10k

Ajax实现搜索联想 搜索关键词提醒 无刷新搜索
通过javascript监听搜索框的内容,调用后端即可。(1)javascript监听搜索框的内容(2)把搜索框的关键词传给后端进行搜索(3)搜索到结果,遍历到页面

TANKING1阅读 4.3k

行易难

513 声望
36 粉丝
宣传栏