Swagger 生成 PHP API 接口文档

Lumen微服务生成Swagger文档


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、参考资料

原文地址:https://segmentfault.com/a/1190000016735909

Swagger 生成 PHP API 接口文档的更多相关文章

  1. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

  2. Asp.Net Core2.0 WebAPI 使用Swagger生成漂亮的接口文档

    1.引用NuGet: Swashbuckle.AspNetCore.Swagger Swashbuckle.AspNetCore.SwaggerGen 或 <PackageReference I ...

  3. 自动生成web api接口文档

    然后打开web程序,访问ip:port/Help. 为什么可以直接输入Help就能访问呢,因为这个插件本身已经配置了路径,如下. public class HelpPageAreaRegistrati ...

  4. spring boot使用swagger生成api接口文档

    前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...

  5. Swagger解决你手写API接口文档的痛

    首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛     苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...

  6. SpringBoot + Swagger2 自动生成API接口文档

    spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...

  7. Api接口文档管理工具,你知道哪些呢?

    上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...

  8. 构建标准OpenStack API接口文档

    1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...

  9. api(接口)文档管理工具

    api(接口)文档管理工具 欢迎光临:博之阅API管理平台  ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全  

随机推荐

  1. selenim

    一.安装selenium Pip install selenium==2.53.1    (稳定版) 下载火狐浏览器35.0.1  http://dl.pconline.com.cn/download ...

  2. 进程线程之pid,tid

    Linux中,每个进程有一个pid,类型pid_t,由getpid()取得.Linux下的POSIX线程也有一个id,类型pthread_t,由pthread_self()取得,该id由线程维护,其i ...

  3. loging模块

    logging模块 什么是logging模块 logging模块是python提供的用于记录日志的模块 为什么需要logging 我们完全可以自己打开文件然后,日志写进去,但是这些操作重复且没有任何技 ...

  4. 计算机网络Intro

    1. 计算机网络体系结构 1.1 简介 定义 计算机网络的各层 + 其协议的集合 作用 定义该计算机网络的所能完成的功能 1.2 结构介绍 计算机网络体系结构分为3种:OSI体系结构.TCP / IP ...

  5. linux内存随笔

    内存在电脑中使用广泛,比如内存条内存.显卡显存.cpu缓存.raid卡缓存等,缓存就是数据交换的缓冲区(称作cache),缓存往往都是RAM(断电文件丢失),他们的读写速率非常高,用来帮助硬件更快的响 ...

  6. STM32 软件模拟 IIC 代码,标准库、HAL库可用

    #ifndef _IIC_H #define _IIC_H #include "stdio.h" #include "stm32f1xx_hal.h" /* 定 ...

  7. 读取bin文件,并且按结构体赋值打印

    目标:读取一个bin文件,并且将bin文件中的数据,按字节对齐赋值给结构体,并且打印出结构体的内容 目前思路是简单的先将bin文件数据一次性读到一个数组中,再将数组强制转换为结构体 ] FILE *f ...

  8. java中的instanceof用法

    Java 中的instanceof 运算符是用来在运行时指出对象是否是特定类的一个实例.instanceof通过返回一个布尔值来指出,这个对象是否是这个特定类或者是它的子类的一个实例. 用法:     ...

  9. 【【henuacm2016级暑期训练】动态规划专题 H】Greenhouse Effect

    [链接] 我是链接,点我呀:) [题意] 在这里输入题意 [题解] 原题意等价于:给你一个序列(实数的位置没用!)..你可以改变其中某些元素的位置(插入到某些位置中间. 然后让他变成有序的. (有序的 ...

  10. DQL查询语句使用(select)

      9)DQL查询语句使用   SELECT语句在PL/SQL中使用,必须 采用下面用法:     select id INTO 变量   from t001 where id=5;    将记录字段 ...