NelmioApiDocBundle
编辑本页NelmioApiDocBundle
的NelmioApiDocBundlebundle允许您以OpenAPI版本2 (Swagger)欧宝官网下载app格式生成文档,并提供了一个沙盒来交互地试验API。
支持什么?
这个bundle支持ob娱乐下载路由要求,PHP注释,Swagger-Php注释,FOSRestBundle使用注释和应用程序接口平台.
对于模型,它支持ob娱乐下载Symfony序列化器,JMS序列化器和willdurand / Hateoas图书馆。它也支持ob娱乐下载Symfony的形式类型。
安装
打开命令控制台,进入您的项目目录并执行以下命令来下载此包的最新版本:
1
$ composer require nelmio/api-doc-bundle:^3.0
请注意
如果你没有使用Flex,那么将bundle添加到你的内核:
12 3 4 5 6 7 8 9 10 11 12 13
类AppKernel扩展内核{公共函数registerBundles():可迭代的{$包= (/ /……新Nelmio \ ApiDocBundle \ NelmioApiDocBundle ()];/ /……}}
要使用Swagger UI浏览欧宝官网下载app您的文档,请注册以下路由:
1 2 3 4 5
#配置/ routes.yamlapp.swagger_ui:路径:/ api /医生方法:得到默认值:{_controller:nelmio_api_doc.controller.swagger_ui}
如果你还想以JSON形式公开它,请注册以下路由:
1 2 3 4 5
#配置/ routes.yamlapp.swagger:路径:/ api / doc.json方法:得到默认值:{_controller:nelmio_api_doc.controller.swagger}
当您刚刚安装包时,您可能会在文档中看到不想要的路由,例如欧宝官网下载app/ _profiler /
.为了解决这个问题,你可以通过配置bundle来过滤记录的路由:
1 2 3 4 5 6 7
#配置/包/ nelmio_api_doc.yamlnelmio_api_doc:领域:path_patterns:#一个regexp数组-^ / api (? ! / doc美元)host_patterns:-^ \ api。
这个包是如何工作的?
它从你的Symfony应用中生成一个OpenAP欧宝官网下载appI文档ob娱乐下载意思.一个从SwaggerPHP注释中提取数据,一个从路由中提取数据,等等。
如果您配置了app.swagger_ui
路径,您可以在'欧宝官网下载apphttp://example.org/api/doc”。
使用捆绑包
您可以在bundle配置中配置全局信息欧宝官网下载appdocumentation.info
Section(看一下。OpenAPI 2.0规范(以前的Swagger)了解可用的字段):
12 3 4 5 6 7 8 9 10 11 12 13 14 15 16
nelmio_api_doc:欧宝官网下载app文档:主持人:api.example.com计划:(http、https)信息:标题:我的应用程序描述:这是一个太棒了应用程序!版本:1.0.0securityDefinitions:持票人:类型:apiKey描述:“值:持有者{jwt}”名称:授权:头安全:-持票人:[]
请注意
如果您正在使用Flex,这个配置默认存在。不要忘记调整它到你的应用程序!
要记录路由,可以使用SwaggerPHP注释和Nelmio \ ApiDocBundle \注释\模型
控制器中的注释:
12 34 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
名称空间AppBundle\控制器;使用AppBundle\实体\用户;使用AppBundle\实体\奖励;使用Nelmio\ApiDocBundle\注释\模型;使用Nelmio\ApiDocBundle\注释\安全;使用昂首阔步\注释作为SWG;使用ob娱乐下载\组件\路由\注释\路线;类用户控件{/** *列出指定用户的奖励* *此呼叫考虑所有已确认的奖励,但不考虑未决或拒绝的奖励。* *@Route("/api/{user}/rewards", methods={"GET"}) *@SWG\Response(* Response =200, * description="返回用户的奖励",*@SWG\Schema(* type="array", * .@SWG(ref = \项目@ model(type=Reward::class, groups={"full"})) *) *) *@SWG\参数(* name="order", * in="query", * type="string", * description="用于订购奖励的字段" *)*@SWG\标记(name = "回报")*@Security(name =“持票人”)* /公共函数fetchUserRewardsAction(用户$用户){/ /……}}
控制器方法上的正常PHPdoc块用于摘要和描述。
使用模型
如上面的示例所示,包提供@ model
注释。使用它而不是定义引用,bundle将推断出您的模型属性。
请注意
模型可以是Symfony表单类型、ob娱乐下载Doctrine ORM实体或通用PHP对象。
这个注释有两个选项:
类型
要指定模型的类型:1 2 3 4 5 6
/ * * *@SWG\Response(* Response =200, * .@ model(type=User::class) *) */
组
要指定用于(反)序列化模型的序列化组:1 2 3 4 5 6
/ * * *@SWG\Response(* Response =200, * .@ model(type =用户::类、组= {" non_sensitive_data "}) * ) */
提示
用于…的词根时@SWG \响应
而且@SWG \参数
,@ model
自动嵌套在@SWG \模式
.
使用@ model
直接在@SWG \模式
,@SWG \物品
或@SWG \房地产
,你必须使用$ ref
字段:
12 3 4 5 6 7 8 9 10 11 12 13
/ * * *@SWG\响应(*@SWG(ref = \模式@ model(type=User::class)) *) * *或* *@SWG\响应(*@SWG\模式(type = "对象",*@SWG\属性(属性= " foo ", ref =@ model(type=FooClass::class)) *) *) */
ob娱乐下载Symfony窗体类型
控件可以自定义表单字段的文档欧宝官网下载app欧宝官网下载app
选择:
1 2 3 4 5 6
$构建器->add (“用户名”, TextType::类,“欧宝官网下载app文档”= > [“类型”=>“字符串”,//在这种情况下会自动检测到“描述”=>你的用户名。,],]);
看到OpenAPI 2.0规范控件的所有可用字段欧宝官网下载app
选择。
一般PHP对象
提示
如果您没有使用JMS序列化器,ob娱乐下载Symfony PropertyInfo组件用于描述您的模型。它支持理论注释、类型提示,甚至PHP文档块。在使用Symfony序列化器时,它也支持序列化组。ob娱乐下载
如果您正在使用JMS序列化器,缺省情况下使用JMS序列化器的元数据来描述模型。附加信息从PHP文档块注释中提取,但是属性类型必须在JMS注释中指定。
如果你喜欢用ob娱乐下载Symfony PropertyInfo组件(你不能使用JMS序列化组),你可以在你的配置中禁用JMS序列化器支持:
1 2
nelmio_api_doc:模型:{use_jms:假}
当使用JMS序列化器与willdurand / Hateoas(和BazingaHateoasBundle),自动提取HATEOAS元数据
如果希望自定义对象属性的文档,可以使用欧宝官网下载app@SWG \房地产
:
12 3 4 5 6 7 8 9 10 11 12 13 14 16 17 18 19 20 21
使用Nelmio\ApiDocBundle\注释\模型;使用昂首阔步\注释作为SWG;类用户{/ * * *@varint *@SWG\属性(description="用户的唯一标识符")*/公共$id;/ * * *@SWG\属性(type="string", maxLength=255) */公共$用户名;/ * * *@SWG(ref = \属性@ model(type =用户::类))* /公共$朋友;}
看到OpenAPI 2.0规范的所有可用字段@SWG \房地产
.