Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档
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
结果如图:
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文档不完全指南
原文地址:https://segmentfault.com/a/1190000016735909
Swagger 生成 PHP API 接口文档的更多相关文章
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- Asp.Net Core2.0 WebAPI 使用Swagger生成漂亮的接口文档
1.引用NuGet: Swashbuckle.AspNetCore.Swagger Swashbuckle.AspNetCore.SwaggerGen 或 <PackageReference I ...
- 自动生成web api接口文档
然后打开web程序,访问ip:port/Help. 为什么可以直接输入Help就能访问呢,因为这个插件本身已经配置了路径,如下. public class HelpPageAreaRegistrati ...
- spring boot使用swagger生成api接口文档
前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...
- Swagger解决你手写API接口文档的痛
首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛 苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...
- SpringBoot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...
- Api接口文档管理工具,你知道哪些呢?
上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...
- 构建标准OpenStack API接口文档
1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...
- api(接口)文档管理工具
api(接口)文档管理工具 欢迎光临:博之阅API管理平台 ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全
随机推荐
- selenim
一.安装selenium Pip install selenium==2.53.1 (稳定版) 下载火狐浏览器35.0.1 http://dl.pconline.com.cn/download ...
- 进程线程之pid,tid
Linux中,每个进程有一个pid,类型pid_t,由getpid()取得.Linux下的POSIX线程也有一个id,类型pthread_t,由pthread_self()取得,该id由线程维护,其i ...
- loging模块
logging模块 什么是logging模块 logging模块是python提供的用于记录日志的模块 为什么需要logging 我们完全可以自己打开文件然后,日志写进去,但是这些操作重复且没有任何技 ...
- 计算机网络Intro
1. 计算机网络体系结构 1.1 简介 定义 计算机网络的各层 + 其协议的集合 作用 定义该计算机网络的所能完成的功能 1.2 结构介绍 计算机网络体系结构分为3种:OSI体系结构.TCP / IP ...
- linux内存随笔
内存在电脑中使用广泛,比如内存条内存.显卡显存.cpu缓存.raid卡缓存等,缓存就是数据交换的缓冲区(称作cache),缓存往往都是RAM(断电文件丢失),他们的读写速率非常高,用来帮助硬件更快的响 ...
- STM32 软件模拟 IIC 代码,标准库、HAL库可用
#ifndef _IIC_H #define _IIC_H #include "stdio.h" #include "stm32f1xx_hal.h" /* 定 ...
- 读取bin文件,并且按结构体赋值打印
目标:读取一个bin文件,并且将bin文件中的数据,按字节对齐赋值给结构体,并且打印出结构体的内容 目前思路是简单的先将bin文件数据一次性读到一个数组中,再将数组强制转换为结构体 ] FILE *f ...
- java中的instanceof用法
Java 中的instanceof 运算符是用来在运行时指出对象是否是特定类的一个实例.instanceof通过返回一个布尔值来指出,这个对象是否是这个特定类或者是它的子类的一个实例. 用法: ...
- 【【henuacm2016级暑期训练】动态规划专题 H】Greenhouse Effect
[链接] 我是链接,点我呀:) [题意] 在这里输入题意 [题解] 原题意等价于:给你一个序列(实数的位置没用!)..你可以改变其中某些元素的位置(插入到某些位置中间. 然后让他变成有序的. (有序的 ...
- DQL查询语句使用(select)
9)DQL查询语句使用 SELECT语句在PL/SQL中使用,必须 采用下面用法: select id INTO 变量 from t001 where id=5; 将记录字段 ...