作为一个phper，在使用Lumen框架开发微服务的时候，API文档的编写总是少不了的。比较流行的方式是用swagger来写API文档，但是和Java语言原生支持的注解不同。PHP只能单独维护一个swagger文档，或者在注释中添加注解来实现类似的功能，但是在注释中写Swagger注解非常痛苦，没有代码提示，也没有格式化。本文将告诉大家如何借助phpstorm中的annotations插件，在开发Lumen微服务项目（Laravel项目类似其他php项目方法）时，快速在代码中使用注解创建swagger文档。本文将不断修订更新。最新内容可以参考我的GITHUB上的程序员成长计划项目。欢迎来到星空。更多精彩内容，请关注我。我们使用最新的Lumen5.7来演示框架配置。demo代码放在github上。有兴趣的可以参考https://github.com/mylxsw/lumen-swagger-demo。安装依赖于Lumen项目。首先，您需要使用composer安装SwaggerLume项目。composer需要darkaonline/swagger-lume项目在bootstrap/app.php文件中配置，去掉下面配置的注释（大约第26行），并开启Facades支持。$app->withFacades();启用S??waggerLume项目的配置文件，在RegisterContainerBindings部分前面添加$app->configure('swagger-lume')；然后，在RegisterServiceProviders部分，注册SwaggerLume的ServiceProvider$app->register(\SwaggerLume\ServiceProvider::class);在项目根目录下，执行命令phpartisanswagger-lume:publish发布swagger相关配置执行该命令后，主要体现在config/目录下有如下变化，新增项目配置文件swagger-lume。resources/views/vendor目录下的index.php，并生成了swagger-lume/index.blade.php视图文件，用于预览生成的API文档从配置文件中，我们可以得到如下键信息api.title生成的API文档显示titleroutes.api用于访问生成的API文档UI默认路由地址为/api/documentationroutes.docs用于访问生成的API文档原文，json格式，默认路由地址为/docspaths的组合.docs和paths.docs_json生成api-docs.json文件的地址。默认为storage/api-docs/api-docs.json。执行phpartisanswagger-lume:generate命令时，会自动提示文件的语法纯手写的swagger注释肯定没必要，太容易出错了，需要一直看文档参考语法，所以我们有必要安装一个可以在注解中自动提示注解语法的插件。我们常用的IDE是phpstorm，在phpstorm中，需要安装PHP注解插件。安装插件后，我们在编写Swagger文档时，有代码自动提示功能。编写文档Swagger文档包含大量与具体API无关的信息。在我所在的控制器中创建一个SwaggerController它们不实现业务逻辑，只是用来放置一般的文档信息\Schema;useOpenApi\Annotations\Server;/****@Info(*version="1.0.0",*title="DemoService",*description="这是一个demo服务，本文档提供demoswaggerapi函数",*@Contact(*email="mylxsw@aicode.cc",*name="mylxsw"*)*)**@Server(*url="http://localhost",*description="开发environment",*)**@Schema(*schema="ApiResponse",*type="object",*description="响应实体，响应结果使用该结构",*title="Responseentity",*@Property(*property="code",*type="string",*description="responsecode"*),*@Property(property="message",type="string",description="responseresultprompt")*)***@packageApp\Http\Controllers*/classSwaggerController{}接下来，在业务l逻辑控制器，我们可以编写APIname=$request->input('name');$resp->id=123;$resp->age=$request->input('age');$resp->gender=$request->input('性别');$prop1=newDemoAdditionalProperty();$prop1->key="foo";$prop1->价值=“酒吧”；$prop2=newDemoAdditionalProperty();$prop2->key="foo2";$prop2->value="bar2";$resp->properties=[$prop1,$prop2];返回$resp;}}这里，在响应结果中，我们引用了SwaggerController中定义的ApiResponse，还引用了一个未定义的ExampleResp对象，我们可以在app\Http\Responses目录下实现（自己创建目录），我们将响应对象放在这个目录
