是否有记录 GET/POST 参数的标准？

php phpdoc doxygen javadoc

2022-08-30 22:27:09

在PHP项目中，即使将前端控制器逻辑用于主应用程序，也可能有许多独立的脚本，ajax片段等。

有没有一种标准化的方法 - PHPDoc或其他东西 - 在脚本的第一个注释块中定义脚本将接受/需要的GET和/或POST参数以及它们的类型？

我通常通过添加s来帮助自己，就好像文件是一个函数一样，并解释了脚本的作用和返回的内容，但也许有一种更专业的方式我不知道。@param@return

答案 1

phpDocumentor不喜欢@param，并在文件级文档块中@return标签...

如果您选择一个单独的文件来记录它们，根据Mr-sk的答案，您可以使用@link指向那里，但它不会立即显示在文件的文档页面中...它只是一个超链接，您必须单击它才能查看信息。如果您希望该文件的任何内容在脚本文件的文档页面上可见，则可以使用内联 {@example} 标记指向它，甚至仅使用其中的某些行，例如 {@example /path/to/file 3 5} 仅显示第三行到第五行。

在这种情况下，我可能会选择在文件级文档块的长描述中解释一些事情，因为实际上没有直接的方法可以将你的参数标记到phpDocumentor无论如何都会将它们识别为代码元素的位置。如果我在描述中使用的任何参数确实是源自代码中其他位置的文档代码元素，我将使用内联 {@link} 标记指向该代码元素。

例如，假设在另一个代码文件中定义了一些常量，并且在解析另一个文件时会生成这些元素自己的文档。如果我在纯脚本文件（如您的）的文件级文档块中编写的长描述将这些常量作为参数，那么我的句子可能是：

If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

引用：

内联 {@example} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
内联 @{link} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

答案 2

佩卡，

我会考虑使用WADL来记录与您的API的交互。它没有直接回答您的问题 - 因为它不是从源代码文档，其XML中生成的，而是单独维护的。

它确实直接回答了这个问题：

脚本将接受/需要哪些 GET 和/或 POST 参数以及它们的类型

您可以将示例有效负载与 URI 参数、接受的内容类型、错误代码/响应/有效负载一起放在文档中。我发现它非常有价值，并且使用WADL，有人可以针对您的API对客户端进行编码。