NelmioApiDocBundle
编辑本页NelmioApiDocBundle
的NelmioApiDocBundlebundle允许您以OpenAPI (Swagger)格式生欧宝官网下载app成文档，并提供了一个沙盒来交互地试验API。
支持什么?
这个bundle支持ob娱乐下载路由要求，PHP注释，Swagger-Php注释,FOSRestBundle使用的注释和应用程序接口平台．
对于模型，它支持ob娱乐下载Symfony序列化器,JMS序列化器和willdurand / Hateoas图书馆。它也支持ob娱乐下载Symfony的形式类型。
属性在4.7和PHP 8.1中得到支持。
安装
打开命令控制台，进入您的项目目录并执行以下命令来下载此包的最新版本:
1
$ composer需要nelmio/api-doc-bundle缺省情况下，只有下的路由/ api是记录。更新regexp atnelmio_api_doc.areas.path_patterns在配置/包/ nelmio_api_doc.yaml改变这一政策。
请注意
如果你没有使用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，只包含/api下的文档路由)-^ / api (? ! / doc美元)host_patterns:#文档只路由api.*形式的主机-^ \ api。这个包是如何工作的?
它从你的Symfony应用中生成一个OpenAP欧宝官网下载appI文档ob娱乐下载意思．一个从SwaggerPHP注释中提取数据，一个从路由中提取数据，等等。
如果您配置了app.swagger_ui路径，您可以在'欧宝官网下载apphttp://example.org/api/doc｀.
使用捆绑包
您可以在bundle配置中配置全局信息欧宝官网下载appdocumentation.infoSection(看一下。OpenAPI 3.0规范(以前的Swagger)以了解可用的字段)。
12 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
nelmio_api_doc:欧宝官网下载app文档:服务器:-url:http://api.example.com/unsafe描述:API在HTTP-url:https://api.example.com/secured描述:API在HTTPS信息:标题:我的应用程序描述:这是一个太棒了应用程序!版本:1．0．0组件:securitySchemes:持票人:类型:http方案:持票人bearerFormat:JWT安全:-持票人:［］请注意
如果您正在使用Flex，这个配置默认在下面配置/包/ nelmio_api_doc.yaml．不要忘记调整它到你的应用程序!
提示
这个配置字段通常用于将文档存储为yaml。欧宝官网下载app你可以在.yaml文件从SwaggerPHP例子．
要记录路由，可以使用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＼注释＼安全；使用OpenApi＼注释作为办公自动化；使用ob娱乐下载＼组件＼路由＼注释＼路线；类用户控件｛/** *列出指定用户的奖励* *此呼叫考虑所有已确认的奖励，但不考虑未决或拒绝的奖励。* *@Route("/api/{user}/rewards"， methods={"GET"}) *@OA\Response(* Response =200， * description="返回用户的奖励"，*@OA\JsonContent(* type="array"， * .@OA(ref = \项目@ model(type=Reward::class, groups={"full"})) *) *) *@OA\参数(* name="order"， * in="query"， * description="用于订购奖励的字段"，*@OA\Schema(type="string") *) *@OA\标记(name = "回报")*@Security(name =“持票人”)* /公共函数fetchUserRewardsAction(用户＄用户）｛/ /……}}控制器方法上的正常PHPDoc块用于摘要和描述。
提示
使用注释的示例可以在SwaggerPHP例子．然而，与这些例子不同的是，当使用这个包时，您不需要指定路径，并且可以轻松地记录模型以及下面描述的一些其他属性，因为可以使用Symfony集成自动记录它们。ob娱乐下载
使用模型
如上面的示例所示，包提供@ model注释。使用它而不是定义引用，bundle将推断出您的模型属性。
请注意
模型可以是Symfony表单类型、ob娱乐下载Doctrine ORM实体或通用PHP对象。
这个注释有两个选项:
类型要指定模型的类型:
- 注释
- 属性
1 2 3 4 5 6
/ * * *@OA\Response(* Response =200， * .@ model(type=User::class) *) */组要指定用于(反)序列化模型的序列化组:
- 注释
- 属性
1 2 3 4 5 6
/ * * *@OA\Response(* Response =200， * .@ model(type =用户::类、组= {" non_sensitive_data "}) * ) */组也可以用来指定使用(反)序列化模型的约束验证组，但这必须在配置中启用:
1 2 3
nelmio_api_doc:use_validation_groups:真正的#……启用此功能后，在模型中设置的组将应用于序列化器属性和验证器约束。请看下面的模型类:
- 注释
- 属性
1 2 3 4 5 6 7 8 9 10 11
使用ob娱乐下载＼组件＼序列化器＼注释＼组；使用ob娱乐下载＼组件＼验证器＼约束作为断言；类UserDto｛/ * * *@Groups({"default"， "create"， "update"}) *@Assert\NotBlank(groups={"default"， "create"}) */公共字符串＄用户名；｝的NotBlank约束将仅应用于默认的而且创建组，但不是更新．在更实际的术语中:' username '属性将显示为要求对于模型创建和默认，但不更新。当使用代码生成器构建API客户端时，这通常转化为客户端验证和类型。NotBlank添加要求例如，将导致该属性类型不可为空。
- 注释
- 属性
12 3 4 5 6 7 8 9 10 11 12 13 14 16 17 18 19 20
使用OpenApi＼注释作为办公自动化；/** *在OpenAPI模式中显示' username '为' required '(不可为空)*@OA\Response(* Response =200， * .@ model(type=UserDto::class, groups={"default"}) *) *//** *类似地，这将使用户名在create * schema *中为' required '@OA\ RequestBody (@ model(type=UserDto::class, groups={"create"})) *//** *但对于更新，' username '属性将不需要*@OA\ RequestBody (@ model(type=UserDto::class, groups={"update"})) */提示
用于…的词根时@OA \响应而且@OA \参数，@ model自动嵌套在@OA \模式．
媒体类型默认为application / json．
使用@ model直接在@OA \模式，@OA \物品或@OA \房地产，你必须使用$ ref字段:
- 注释
- 属性
12 3 4 5 6 7 8 9 10 11 12 13
/ * * *@OA\响应(*@OA\ JsonContent (ref =@ model(type=User::class)) *) * *或* *@OA\响应(@OA\ XmlContent (*@OA\模式(type = "对象",*@OA\属性(属性= " foo ", ref =@ model(type=FooClass::class)) *) *) */ob娱乐下载Symfony窗体类型
控件可以自定义表单字段的文档欧宝官网下载app欧宝官网下载app选择:
1 2 3 4 5 6
＄构建器->add (“用户名”, TextType：：类,“欧宝官网下载app文档”= > [“类型”= >“字符串”，//在这种情况下会自动检测到“描述”= >你的用户名。，]，]);看到OpenAPI 3.0规范控件的所有可用字段欧宝官网下载app选项(它接受与OpenApi相同的字段财产对象)。
一般PHP对象
提示
如果您没有使用JMS序列化器,ob娱乐下载Symfony PropertyInfo组件用于描述您的模型。它支持理论注释、类型提示，甚至PHP文档块。在使用Symfony序列化器时，它也支持序列化组。ob娱乐下载
如果您正在使用JMS序列化器，缺省情况下使用JMS序列化器的元数据来描述模型。附加信息从PHP文档块注释中提取，但是属性类型必须在JMS注释中指定。
注意:如果你正在使用序列化上下文(例如组)，每个排列将被视为一个单独的路径。例如，如果你在代码的不同位置定义了以下两个变量:
12 3 4 5 6 7 8 9 10 11 12 13
/** *没有上下文组**的嵌套序列化器属性@JMS\ VirtualProperty *@JMS\类型(“ArrayCollection < App \响应\ ItemResponse >”)*@JMS\自("1.0")* *@return收藏| ItemResponse [] * /公共函数getItems（）：集合|数组｛返回＄这->项目;｝- 注释
- 属性
1
@OA \模式(ref = @ model (type =“应用程序\ \ ItemResponse反应”、组= [“默认”))),它将生成两个不同的组件模式(ItemResponse, ItemResponse2)，即使Default和blank是相同的。这是有意为之。
如果你喜欢用ob娱乐下载Symfony PropertyInfo组件(你不能使用JMS序列化组)，你可以在你的配置中禁用JMS序列化器支持:
1 2
nelmio_api_doc:模型:｛use_jms:假｝当使用JMS序列化器与willdurand / Hateoas(和BazingaHateoasBundle)，自动提取HATEOAS元数据
如果希望自定义对象属性的文档，可以使用欧宝官网下载app@OA \房地产：
- 注释
- 属性
12 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
使用Nelmio＼ApiDocBundle＼注释＼模型；使用OpenApi＼注释作为办公自动化；类用户｛/ * * *@varint *@OA\属性(description="用户的唯一标识符")*/公共＄id；/ * * *@OA\属性(type="string"， maxLength=255) */公共＄用户名；/ * * *@OA(ref = \属性@ model(type =用户::类))* /公共＄朋友；/ * * *@OA\属性(description="这是我的同事!")*/公共setCoworker(用户＄同事) {/ /……}}看到OpenAPI 3.0规范的所有可用字段@OA \房地产．
