Lumen微服务生成Swagger文档

alighters 发布于2019-07-01 11:08 / 3310人阅读

摘要：本文将会告诉你如何借助中插件，在开发微服务项目时项目和其它项目方法类似快速的在代码中使用注释来创建文档。本文将会持续修正和更新，最新内容请参考我的上的程序猿成长计划项目，欢迎，更多精彩内容请。框架配置我们使用当前最新的来演示。

作为一名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

项目配置

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

$app->withFacades();

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

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

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

$app->register(SwaggerLumeServiceProvider::class);

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

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

在 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.docs 和 paths.docs_json 组合生成 api-docs.json 文件的地址，默认为 storage/api-docs/api-docs.json，执行php artisan swagger-lume:generate命令时，将会生成该文件

语法自动提示

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

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

书写文档

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


接下来，在业务逻辑控制器中，我们就可以写API了
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对象，我们可以 appHttpResponses 目录（自己创建该目录）中实现该ExampleResp对象，我们将响应对象都放在这个目录中

返回对象引用其它对象

生成文档
执行下面的命令，就可以生成文档了，生成的文档在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文档，感兴趣的不妨尝试一下。

GPU云服务器云服务器微服务部署文档生成 python生成文档 python文档生成

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

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

微服务横行的今天, 你的文档跟上节奏了么?

摘要：纳尼隔壁少林派表示自家金刚技压群雄在座各位都是。。。纳尼你觉得写太繁琐了你不喜欢我们还有或者等等一大堆工具呢。纳尼没有你还是觉得无法接受好吧那么笔者推荐类似这类更友好的工具你可以导入导出其他格式也可以使用其来撰写。说起微服务, 想必现在的技术圈内人士个个都能谈笑风云, 娓娓道来。的确, 技术变革日新月异, 各种工具框架雨后春笋般涌现, 现在我们可以轻巧便捷地根据自己的业务需求, 构建...

liaoyg8023 2019-08-14 16:55 评论0 收藏0
[直播视频] 《Java 微服务实践 - Spring Boot 系列》限时折扣

摘要：作为微服务的基础设施之一，背靠强大的生态社区，支撑技术体系。微服务实践为系列讲座，专题直播节，时长高达小时，包括目前最流行技术，深入源码分析，授人以渔的方式，帮助初学者深入浅出地掌握，为高阶从业人员抛砖引玉。简介目前业界最流行的微服务架构正在或者已被各种规模的互联网公司广泛接受和认可，业已成为互联网开发人员必备技术。无论是互联网、云计算还是大数据，Java平台已成为全栈的生态体系，...

Enlightenment 2019-08-16 10:45 评论0 收藏0
微服务实战：从架构到发布（一）

摘要：微服务集成服务间通信微服务架构下，应用的服务直接相互独立。微服务架构倾向于降低中心消息总线类似于的依赖，将业务逻辑分布在每个具体的服务终端。引言：微服务是当前软件架构领域非常热门的词汇，能找到很多关于微服务的定义、准则，以及如何从微服务中获益的文章，在企业的实践中去应用微服务的资源却很少。本篇文章中，会介绍微服务架构（Microservices Architecture）的基础概念，...

libin19890520 2019-08-14 15:19 评论0 收藏0
微服务实战：从架构到发布（一）

摘要：微服务集成服务间通信微服务架构下，应用的服务直接相互独立。微服务架构倾向于降低中心消息总线类似于的依赖，将业务逻辑分布在每个具体的服务终端。引言：微服务是当前软件架构领域非常热门的词汇，能找到很多关于微服务的定义、准则，以及如何从微服务中获益的文章，在企业的实践中去应用微服务的资源却很少。本篇文章中，会介绍微服务架构（Microservices Architecture）的基础概念，...

HtmlCssJs 2019-06-26 17:01 评论0 收藏0