NelmioApiDocBundle

版本: 当前的
编辑这个页面

NelmioApiDocBundle

NelmioApiDocBundleBUNDLE允许您在OpenAPI(Swagger)格式中生欧宝官网下载app成文档,并提供沙箱以与API交互实验。

支持什么?

这个包支持ob娱乐下载路由要求,PHP注释,Swagger-PHP.注释,fosrestbundle.注释和应用程序使用接口平台

对于模型,它支持ob娱乐下载Symfony序列化器,JMS Serializer.Willdurand / Hateoas.图书馆。它也支持ob娱乐下载symfony形式类型。

安装

打开一个命令控制台,输入您的项目目录,并执行以下命令下载该包的最新版本:

1
$ Composer需要Nelmio / API-Doc-Bundle

请注意

如果你没有使用Flex,那就把这个包添加到你的内核中:

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 5
#配置/ routes.yamlapp.swagger_ui:路径:/ api /医生方法:得到默认值:_controller:nelmio_api_doc.controller.swagger_ui

如果你还想在JSON中暴露它,请注册以下路由:

1 2 3 4 5 5
#配置/ routes.yamlapp.swagger:路径:/api/doc.json.方法:得到默认值:_controller:nelmio_api_doc.controller.swagger

正如您刚刚安装了捆绑包,您可能会看到您在文档中不需要的路由,例如欧宝官网下载app/ _profiler /.要解决此问题,您可以通过配置包来过滤记录的路由:

1 2 3 4 5 6 7
#配置/包/ nelmio_api_doc.yamlnelmio_api_doc:领域:path_patterns:#regexps数组-^ / api (? ! / doc美元)host_patterns:-^ \ api。

这个包是如何工作的?

它从Symfony应用程序生成OpenAPI文档欧宝官网下载app,感谢ob娱乐下载意思.一个从SwaggerPHP注释中提取数据,一个从你的路由中提取数据,等等。

如果您配置了app.swagger_ui上面的路线,您可以在“”中“浏览您的文档欧宝官网下载apphttp://example.org/api/doc`。

使用捆绑

您可以在bundle配置中配置全局信息欧宝官网下载app文档.Info.部分(看看OpenAPI 3.0规范(以前的Swagger)要了解可用的字段):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 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,则默认情况下此配置。不要忘记将它调整到您的应用程序!

要记录路由,您可以使用SwaggeLphp注释和nelmio \ apidocbundle \ annotation \ model控制器中的注释:

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实体奖励NelmioApiDocBundle注解模型NelmioApiDocBundle注解安全OpenApi注释作为OA.ob娱乐下载组件路由注解路线用户控件/ ** *列出指定用户的奖励。* *此呼吁考虑到所有确认的奖项,但未遵守或拒绝奖励。* *@Route(“/ api / {user} /奖励”,方法={“获得”})*@OA\ response(*响应= 200,*描述=“返回用户的奖励”,*@OA\JsonContent(* type="array", *@OA(ref = \项目@模型(type=Reward::class, groups={"full"})) *) *) *@OA\参数(* name =“顺序”,* in =“查询”,*描述=“用于订购奖励的字段”,*@OA\ schema(type =“字符串”)*)*@OA\标记(name = "回报")*@Security(名称=“持票人”)* /民众功能fetchUserRewardsAction(用户用户/ /……}}

控制器方法上的普通PHPdoc块用于摘要和描述。

使用模型

如上例所示,包提供@模型注解。使用它而不是定义引用,捆绑包将推断您的模型属性。

请注意

模型可以是Symfony表单类型,ob娱乐下载学说ORM实体或常规PHP对象。

这个注释有两个选项:

  • 类型要指定模型的类型:

    1 2 3 4 5 6
    / ** *@OA\响应(*响应=200,*@模型(type=User::class) *) */
  • 团体要指定用于(反)序列化模型的序列化组:

    1 2 3 4 5 6
    / ** *@OA\响应(*响应=200,*@模型(type =用户::类、组= {" non_sensitive_data "}) * ) */

提示

当用于词根时@OA \响应@OA \参数@模型是自动嵌套在@oa \ schema.

媒体类型默认为application / json

使用@模型直接在A内@oa \ schema.@OA \物品或者@OA \房地产,你必须使用$ ref.字段:

12 3 4 5 6 7 8 9 10 11 12 13
/ ** *@OA\响应(*@OA\ JsonContent (ref =@模型(type=User::class)) *) * *或* *@OA\响应(@OA\ XMLContent(*@OA\模式(type = "对象",*@OA\属性(属性= " foo ", ref =@模型(键入= fooclass :: class))*)*))* /

ob娱乐下载Symfony形式类型

您可以使用使用该字段的文档欧宝官网下载app欧宝官网下载app选项:

1 2 3 4 5 6
构建器- >添加('用户名', TextType::班级, [“欧宝官网下载app文档”=> ['类型'=>“字符串”//在这种情况下将自动检测到“描述”=>你的用户名。、]]);

看看OpenAPI 3.0规范的所有可用字段欧宝官网下载app选项(它接受与OpenApi相同的字段财产目的)。

通用PHP对象

提示

如果您未使用JMS Serializer,ob娱乐下载Symfony propertyInfo组件用于描述您的模型。它支持学说注释,键入提示,甚至php doc块。使用Symfony Serializer时,它也会支持序列化组。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 \模式((电子邮件保护)(类型=“app \ response \ itemresponse”,组= [“默认”]),

它将生成两个不同的组件模式(ItemResponse, ItemResponse2),即使Default和blank是相同的。这是设计好的。

如果你更喜欢用ob娱乐下载Symfony propertyInfo组件(你将不能使用JMS序列化组),你可以在你的配置中禁用JMS序列化支持:

1 2
nelmio_api_doc:模型:USE_JMS:

使用JMS序列化器结合使用时Willdurand / Hateoas.(和BazingaHateoasBundle),自动提取HATEOAS元数据

如果要自定义对象属性的文档,则可以使用欧宝官网下载app@OA \房地产

1 2 3 4 5 6 7 8 9 10 11 12 13 13 14 15 16 18 19 20 21 21 22 23 22 22 22 27 22 22 22
NelmioApiDocBundle注解模型OpenApi注释作为OA.用户/ ** *@varint *@OA\属性(描述="用户的唯一标识符")*/民众id/ ** *@OA\属性(类型=“字符串”,最大长度= 255)* /民众用户名/ ** *@OA(ref = \属性@模型(type =用户::类))* /民众朋友/ ** *@OA\属性(description="这是我的同事!")*/民众setCoworker(用户同事) {/ /……}}

看看OpenAPI 3.0规范查看所有可用的字段@OA \房地产

了解更多

如果你需要更复杂的功能,请看: