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

【问题标题】：Is there a standard for documenting GET/POST parameters?是否有记录 GET/POST 参数的标准？
【发布时间】：2011-01-08 11:12:09
【问题描述】：

在PHP项目中，即使主应用使用前端控制器逻辑，也可以有很多独立的脚本，ajax sn-ps等。

是否有一种标准化的方式（PHPDoc 或其他方式）在脚本的第一个注释块中定义脚本将接受/要求的 GET 和/或 POST 参数以及它们的类型？

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

【问题讨论】：

好问题，我也想知道。

标签： php javadoc doxygen phpdoc

【解决方案1】：

phpDocumentor 不喜欢 file-level 文档块中的 @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 编写客户端代码。

【讨论】：

【解决方案3】：

我会使用@uses 或@see 目前我正在使用@uses，因为它读起来更好，更有意义

参考：https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html

【讨论】：