symfony - 如何在 Swagger (OpenApi) 中添加 JSON 请求和响应示例?
问题描述
我的 Symfony 4 应用程序中有一个 API 端点,我想用 NelmioApiDocBundle 和 Swagger 记录它。端点将 JSON 作为请求数据并返回一些自定义 JSON 作为响应。如何使用注释将它们的示例添加到文档中?我在文档页面上看不到任何示例,只有描述。
/**
* @Route("/order/import", methods={"POST"}, name="order_import")
* @OA\RequestBody (
* request="order",
* description="Order data in JSON format",
* @OA\Schema(
* type="object",
* example={"hello": "world"}
* )
* )
* @OA\Response(
* response=200,
* description="Returns the JSON data after import",
* @OA\Schema(
* type="object",
* example={"foo": "bar"}
* )
* )
* @OA\Tag(name="import")
解决方案
对于 NelmioApiDocBundle v4,你可以这样做
use OpenApi\Annotations as OA;
/**
* @OA\Parameter(
* name="body",
* in="path",
* required=true,
* @OA\JsonContent(
* type="object",
* @OA\Property(property="property1", type="number"),
* @OA\Property(property="property2", type="number"),
* ),
* )
*
* @OA\Response(
* response=200,
* description="",
* @OA\JsonContent(
* type="object",
* @OA\Property(property="property1", type="number"),
* @OA\Property(property="property2", type="number"),
* )
* )
*/
对于 v3
use Swagger\Annotations as SWG;
/**
* @SWG\Parameter(
* name="body",
* in="body",
* required=true,
* @SWG\Schema(
* @SWG\Property(property="test1", type="string"),
* @SWG\Property(property="test2", type="string"),
* ),
* )
*
* @SWG\Response(
* description="",
* response=200,
* @SWG\Schema(
* @SWG\Property(property="test1", type="string"),
* @SWG\Property(property="test2", type="string"),
* ),
* )
*/
但如果您有 DTO 或实体,最好通过 @Model 注释来完成,如文档中所述。
推荐阅读
- python - overrideredirect 如何影响 winfo_height/width?
- oracle - Oracle 过程从表中选择数据,从 all_tab_columns 传递列
- c++ - 重载 >> 运算符时的非法指令
- python - 递归地打乱列表
- php - PHP通过带有stdObjects的多维数组进行多次循环
- python - 具有复杂标准的python pandas重复数据删除
- c++ - 无法累积编译时间常数
- selenium - Selenium 无法加载元素,尽管有 EC、等待和滚动尝试
- html - 我可以在 html 页面的 div 内容中添加代码吗?
- c# - File.Exists() 在一个类中有效,但在另一个类中无效,尽管代码是重复的