Laravel Swagger 生成 API 文档

Laravel Swagger 生成 API 文档

1. 安装 l5-swagger

https://github.com/DarkaOnLine/L5-Swagger

2. PHPStorm 安装 php annotations 插件

增加一条别名数据, 下图红线画出来的. 这样就可以有 swagger 的注释提示了.
Laravel Swagger 生成 API 文档

3. 如何编写 注释 进而生成 文档

3.1 学习资源

  1. swagger-php guide
  2. swagger-php 里面有例子,但是我发现好像不是很全
  3. Swagger Editor
  4. swagger 文档

加油好好看!

4. 当前遇到的问题

  1. @AO\Headerswagger ui 中不显示(我用的是 openApi 3.0).

5. 总结

就目前我的体验, 个人感觉这个东西上手稍微有点难, 而且在每个方法前面写 Swagger 的注释很麻烦, 编写文档注释比开发的时间还要长.倒不如直接编写 swagger 读取的 json/ymal 文件.

本作品采用《CC 协议》,转载必须注明作者和本文链接
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
讨论数量: 6

我一般用 apidoc

10个月前 评论

@yanthink apidoc 貌似也不错, 已经入了 swagger 的坑 就暂时先用这个了 :joy:

10个月前 评论

不是@OA吗?你怎么是@AO

6个月前 评论

@zhp_xixi 我擦, 有可能是我写错了. 好久没用 swagger 了, 都忘了. 感觉这个东西太麻烦了. 不喜欢用.

6个月前 评论

头部的 accept 怎么设置

6个月前 评论

@故意 试试这个吧

@OA\Parameter(
   name="Accept",
   required=true,
   in="header",
   description="Accept 请求头",
   @OA\Schema(
      type="string",
      default="application/json"
   )
),
6个月前 评论

请勿发布不友善或者负能量的内容。与人为善,比聪明更重要!