Swagger 生成 PHP API 接口文档

miya 发布于2019-07-01 10:51 / 2566人阅读

摘要：有同学推荐了，是一个简单但功能强大的表达工具。这里介绍使用生成文档的方法。将文档输出值的根目录下，可通过访问此文档。执行结果如图参考资料生成接口文档如何编写基于的文档使用生成文档不完全指南

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 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 结果如图:

4、参考资料

Swagger 生成 PHP restful API 接口文档

如何编写基于 Swagger-PHP 的 API 文档

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

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

Easy Mock

Laravel（PHP）使用Swagger生成API文档不完全指南

专线服务混合云生成API文档接口文档生成工具 api接口文档 api短信接口文档

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

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

Swagger 生成 PHP restful API 接口文档

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

xiaotianyi 2019-06-28 18:43 评论0 收藏0
Swagger PHP使用指南

摘要：，已经好了，试着访问根目录下，比如试试，出现界面就成功了没从先就用命令看下的路由最上面条就是刚刚添加的路由。先说什么是Swagger, Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作. 官网: http://swagg...

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

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

alighters 2019-07-01 11:08 评论0 收藏0
Java | Spring Boot Swagger2 集成REST ful API 生成接口文档

摘要：集成生成接口文档原文简介由于的特性，用来开发变得非常容易，并且结合来自动生成文档变得方便快捷。使用生成，我们可以得到交互式文档。听过与的结合，生成更加完备的文档。接下来将基于与搭建完整的文档系统。 Spring Boot Swagger2 集成REST ful API 生成接口文档原文简介由于Spring Boot 的特性，用来开发 REST ful 变得非常容易，并且结合 Sw...

joyvw 2019-08-16 10:56 评论0 收藏0
Spring Boot中使用Swagger2构建API文档

摘要：使用生成，我们可以得到交互式文档，自动生成代码的以及的发现特性等。方法指定扫描的包会生成文档默认是显示所有接口可以用注解标识该接口不显示。程序员都很希望别人能写技术文档，自己却很不愿意写文档。因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码，接口调用方的抱怨声不绝于耳。而程序员是最擅长偷...

taohonghui 2019-08-15 11:09 评论0 收藏0