laravel+swagger api 开发

最终效果

image.png

1. laravel5.5.* 安装依赖

composer require "darkaonline/l5-swagger:5.5.*"

gihub地址：https://github.com/DarkaOnLine/L5-Swagger

2. 发布文件到config目录及view目录

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

会在config目录生成一个配置文件l5-swagger.php，resources/views/vendor下生成一个l5-swagger/index.blade.php的文件

3. 打开http://domain/api/documentation，应该是提示找不到配置文件
   
   

   image.png
   
   原因是我们没有写api接口文件，新建文件如下（public/docs/api-docs.yaml）：
   
   

   image.png
   
   没错是yaml结尾的文件，当然也可以使用json文件，但是json写这种配置需要写一大堆的双引号、大括号中括号等，修改l5-swagger.php中'docs_json' => 'api-docs.json',为'docs_json' => 'api-docs.yaml',
4. 该配置文件就是我们的api接口文档写的地方，详细配置参考：https://swagger.io/docs/specification/describing-parameters/
5. 写路由web.php

Route::get('/users/{id}',function(){
    return \App\Entity\User::find(1);
});

查看接口是否正常返回

image.png

6. 写接口文档yaml文件

openapi: 3.0.0
info:
  title:  API
  description: 接口文档.
  version: 1.0.0
servers:
  - url: http://plate.test
    description: dev server
paths:
  /users/{id}:
    get:
      summary: 返回用户详情
      description: 返回用户详情
      parameters:
        - name: id
          schema:
            type: integer
            example:
              1
          in: path
          required: true
      responses:
        '200':
          description: 返回正确
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example:
                      1
                  nickname:
                    type: string
                    example:
                      雷芬
        '404':
          description: not found 

再次打开文档页面

image.png

依次点击try it out --> execute 查看返回结果

image.png

图片中有些地方可能不太一样因为我已经修改了，如url地址等，但是整体步骤都是对的，当然swagger还是支持注解的方式写接口的，但是由于写的注解占据控制器大部分内容，不太清晰这里没有测试，可以参考github上面的步骤进行开发。