Lumen微服務生成Swagger文檔

alighters 發布于2019-07-01 11:08 / 3315人閱讀

摘要：本文將會告訴你如何借助中插件，在開發微服務項目時項目和其它項目方法類似快速的在代碼中使用注釋來創建文檔。本文將會持續修正和更新，最新內容請參考我的上的程序猿成長計劃項目，歡迎，更多精彩內容請。框架配置我們使用當前最新的來演示。

作為一名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文檔生成

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/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