文档章节

Lumen微服务生成Swagger文档

mylxsw
 mylxsw
发布于 01/02 16:15
字数 1589
阅读 17
收藏 0

[TOC]

Xnip2019-01-02_16-07-57

作为一名phper,在使用Lumen框架开发微服务的时候,API文档的书写总是少不了的,比较流行的方式是使用swagger来写API文档,但是与Java语言原生支持 annotation 不同,php只能单独维护一份swagger文档,或者在注释中添加annotations来实现类似的功能,但是注释中书写Swagger注解是非常痛苦的,没有代码提示,没有格式化。

本文将会告诉你如何借助phpstorm中annotations插件,在开发Lumen微服务项目时(Laravel项目和其它php项目方法类似)快速的在代码中使用注释来创建swagger文档。

本文将会持续修正和更新,最新内容请参考我的 GITHUB 上的 程序猿成长计划 项目,欢迎 Star,更多精彩内容请 follow me

框架配置

我们使用当前最新的 Lumen 5.7 来演示。演示代码放到了github,感兴趣的可以参考一下

https://github.com/mylxsw/lumen-swagger-demo

安装依赖

在Lumen项目中,首先需要使用 composer 安装SwaggerLume项目依赖

composer require darkaonline/swagger-lume

-w568

项目配置

bootstrap/app.php文件中,去掉下面配置的注释(大约在26行),启用Facades支持。

$app->withFacades();

启用SwaggerLume 项目的配置文件,在 Register Container Bindings部 分前面,添加

$app->configure('swagger-lume');

然后,在 Register Service Providers 部分,注册 SwaggerLume 的ServiceProvider

$app->register(\SwaggerLume\ServiceProvider::class);

在项目的根目录,执行命令 php artisan swagger-lume:publish 发布swagger相关的配置

-w406

执行该命令后,主要体现以下几处变更

-w617

  • config/ 目录中,添加了项目的配置文件 swagger-lume.php
  • resources/views/vendor 目录中,生成了 swagger-lume/index.blade.php 视图文件,用于预览生成的API文档

从配置文件中我们可以获取以下关键信息

  • api.title 生成的API文档显示标题
  • routes.api 用于访问生成的API文档UI的路由地址默认为 /api/documentation
  • routes.docs 用于访问生成的API文档原文,json格式,默认路由地址为 /docs
  • paths.docspaths.docs_json 组合生成 api-docs.json 文件的地址,默认为 storage/api-docs/api-docs.json,执行php artisan swagger-lume:generate命令时,将会生成该文件

语法自动提示

纯手写swagger注释肯定是要不得的,太容易出错,还需要不停的去翻看文档参考语法,因此我们很有必要安装一款能够自动提示注释中的注解语法的插件,我们常用的IDE是 phpstorm,在 phpstorm 中,需要安装 PHP annotation 插件

安装插件之后,我们在写Swagger文档时,就有代码自动提示功能了

2019-01-02 13_33_59

书写文档

Swagger文档中包含了很多与具体API无关的信息,我们在 app/Http/Controllers 中创建一个 SwaggerController,该控制器中我们不实现业务逻辑,只用来放置通用的文档信息

<?php
namespace App\Http\Controllers;

use OpenApi\Annotations\Contact;
use OpenApi\Annotations\Info;
use OpenApi\Annotations\Property;
use OpenApi\Annotations\Schema;
use OpenApi\Annotations\Server;

/**
 *
 * @Info(
 *     version="1.0.0",
 *     title="演示服务",
 *     description="这是演示服务,该文档提供了演示swagger api的功能",
 *     @Contact(
 *         email="mylxsw@aicode.cc",
 *         name="mylxsw"
 *     )
 * )
 *
 * @Server(
 *     url="http://localhost",
 *     description="开发环境",
 * )
 *
 * @Schema(
 *     schema="ApiResponse",
 *     type="object",
 *     description="响应实体,响应结果统一使用该结构",
 *     title="响应实体",
 *     @Property(
 *         property="code",
 *         type="string",
 *         description="响应代码"
 *     ),
 *     @Property(property="message", type="string", description="响应结果提示")
 * )
 *
 *
 * @package App\Http\Controllers
 */
class SwaggerController
{}

接下来,在业务逻辑控制器中,我们就可以写API了

<?php
namespace App\Http\Controllers;

use App\Http\Responses\DemoAdditionalProperty;
use App\Http\Responses\DemoResp;
use Illuminate\Http\Request;
use OpenApi\Annotations\Get;
use OpenApi\Annotations\MediaType;
use OpenApi\Annotations\Property;
use OpenApi\Annotations\RequestBody;
use OpenApi\Annotations\Response;
use OpenApi\Annotations\Schema;

class ExampleController extends Controller
{

    /**
     * @Get(
     *     path="/demo",
     *     tags={"演示"},
     *     summary="演示API",
     *     @RequestBody(
     *         @MediaType(
     *             mediaType="application/json",
     *             @Schema(
     *                 required={"name", "age"},
     *                 @Property(property="name", type="string", description="姓名"),
     *                 @Property(property="age", type="integer", description="年龄"),
     *                 @Property(property="gender", type="string", description="性别")
     *             )
     *         )
     *     ),
     *     @Response(
     *         response="200",
     *         description="正常操作响应",
     *         @MediaType(
     *             mediaType="application/json",
     *             @Schema(
     *                 allOf={
     *                     @Schema(ref="#/components/schemas/ApiResponse"),
     *                     @Schema(
     *                         type="object",
     *                         @Property(property="data", ref="#/components/schemas/DemoResp")
     *                     )
     *                 }
     *             )
     *         )
     *     )
     * )
     *
     * @param Request $request
     *
     * @return DemoResp
     */
    public function example(Request $request)
    {
        // TODO 业务逻辑

        $resp         = new DemoResp();
        $resp->name   = $request->input('name');
        $resp->id     = 123;
        $resp->age    = $request->input('age');
        $resp->gender = $request->input('gender');

        $prop1        = new DemoAdditionalProperty();
        $prop1->key   = "foo";
        $prop1->value = "bar";

        $prop2        = new DemoAdditionalProperty();
        $prop2->key   = "foo2";
        $prop2->value = "bar2";

        $resp->properties = [$prop1, $prop2];

        return $resp;
    }
}

这里,我们在响应结果中,引用了在SwaggerController中定义的 ApiResponse,还引用了一个没有定义的ExampleResp对象,我们可以 app\Http\Responses 目录(自己创建该目录)中实现该ExampleResp对象,我们将响应对象都放在这个目录中

<?php

namespace App\Http\Responses;

use OpenApi\Annotations\Items;
use OpenApi\Annotations\Property;
use OpenApi\Annotations\Schema;

/**
 * @Schema(
 *     title="demo响应内容",
 *     description="demo响应内容描述"
 * )
 *
 * @package App\Http\Responses
 */
class DemoResp extends JsonResponse
{

    /**
     * @Property(
     *     type="integer",
     *     description="ID"
     * )
     *
     * @var int
     */
    public $id = 0;

    /**
     * @Property(
     *     type="string",
     *     description="用户名"
     * )
     *
     * @var string
     */
    public $name;

    /**
     * @Property(
     *     type="integer",
     *     description="年龄"
     * )
     *
     * @var integer
     */
    public $age;

    /**
     * @Property(
     *     type="string",
     *     description="性别"
     * )
     *
     * @var string
     */
    public $gender;

    /**
     * @Property(
     *     type="array",
     *     @Items(ref="#/components/schemas/DemoAdditionalProperty")
     * )
     *
     * @var array
     */
    public $properties = [];
}

返回对象引用其它对象

<?php
namespace App\Http\Responses;

use OpenApi\Annotations\Property;
use OpenApi\Annotations\Schema;

/**
 *
 * @Schema(
 *     title="额外属性",
 *     description="额外属性描述"
 * )
 *
 * @package App\Http\Responses
 */
class DemoAdditionalProperty
{
    /**
     * @Property(
     *     type="string",
     *     description="KEY"
     * )
     *
     * @var string
     */
    public $key;

    /**
     * @Property(
     *     type="string",
     *     description="VALUE"
     * )
     *
     * @var string
     */
    public $value;
}

生成文档

执行下面的命令,就可以生成文档了,生成的文档在storage/api-docs/api-docs.json

php artisan swagger-lume:generate

预览文档

打开浏览器访问 http://访问地址/docs,可以看到如下内容

访问 http://访问地址/api/documentation,我们看到

接口详细信息展开

更多

本文简述了如何在Lumen项目中使用代码注释自动生成Swagger文档,并配合phpstorm的代码提示功能,然而,学会了这些还远远不够,你还需要去了解Swagger文档的语法结构,在 swagger-php 项目的 Examples 目录中包含很多使用范例,你可以参考一下。

团队项目中使用了swagger文档,但是总得有个地方管理文档吧,这里推荐一下 Wizard 项目,该项目是一款用于团队协作的文档管理工具,支持Markdown文档和Swagger文档,感兴趣的不妨尝试一下。

© 著作权归作者所有

共有 人打赏支持
mylxsw

mylxsw

粉丝 30
博文 23
码字总数 53665
作品 8
朝阳
程序员
私信 提问
surging如何使用swagger 组件测试业务模块

1、前言 微服务架构概念的提出已经有非常长一段时间了,但在近期几年却开始频繁地出现,大家都着手升级成微服务架构,使用着各种技术,大家认为框架有服务治理就是微服务,实现单一协议的服务...

fanly11
2018/10/07
0
0
Spring Cloud Gateway 聚合swagger文档

关于pigX:全网最新的微服务脚手架,Spring Cloud Finchley、oAuth2的最佳实践 在微服务架构下,通常每个微服务都会使用Swagger来管理我们的接口文档,当微服务越来越多,接口查找管理无形中...

gggggwww
2018/07/20
0
0
使用Beego+Swagger构建更好的API服务

一. 更好的API服务 在你已经在工作中写了很多版本,很多规范的API服务之后,你会发现,后端服务很多共性的工作需要去完成,比如: 1)良好的API说明文档,最好还附带可访问,试一试的服务url...

skywalker
2017/08/02
0
0
规范代码生成器--Swagger-codegen

OpenAPI (f.k.a Swagger) 规范代码生成器,支持 API clients, API servers 和 API documention: API 客户端:ActionScript, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen),......

wing328
2017/03/13
1K
1
特别好用的swagger ui 封装

Swagger简单介绍 Swagger是一个Restful风格接口的文档在线自动生成和测试的框架 官网:http://swagger.io 官方描述:The World’s Most Popular Framework for APIs. Swagger ui 的原生UI界面...

huanshare
2018/08/13
0
0

没有更多内容

加载失败,请刷新页面

加载更多

eggjs与sequelize简单demo

参考 egg 官方文档 安装 // 依赖npm install --save egg-sequelize mysql2// ts 类型npm install --save @types/sequelize 插件,config/plugin.ts import { EggPlugin } from 'egg';......

Geeyu
41分钟前
1
0
看过上百部片子的这个人教你视频标签算法解析

本文由云+社区发表 随着内容时代的来临,多媒体信息,特别是视频信息的分析和理解需求,如图像分类、图像打标签、视频处理等等,变得越发迫切。目前图像分类已经发展了多年,在一定条件下已经...

腾讯云加社区
56分钟前
2
0
2. 红黑树

定义:红黑树(Red-Black Tree,简称R-B Tree),它一种特殊的二叉查找树(Binary Search Tree)。 要理解红黑树,先要了解什么是二叉查找树。在上一章中,我们学习了什么是二叉树,以及二叉树...

火拳-艾斯
57分钟前
3
0
input的button类型,点击页面跳转

一、input type=button 不做任何操作 例如: <input type="button" class="btn btn-primary" style="width: 30%" value="返回" onclick="window.location.href='/users/list'"></input> onc......

Sunki
今天
1
0
踩坑:js 小数运算出现精度问题

背景 在学习小程序商城源码时发现了这个问题,单价可能出现小数,小数之间运算结果会莫名其妙多出一大串数字,比如下面这样👇。 在此之前我是知道 js 中著名的 0.1 + 0.2 != 0.3 的问题的,...

dkvirus
今天
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部