README

部分移植自 adonis-swagger，并结合 DarkaOnLine/L5-Swagger 的一些工作，以在 yaml 文件中定义 swagger 定义，而不是使用类装饰器定义

注意：本库目前仅支持 swagger api v2！

包含内容

• yaml 全局文件，用于暴露 swagger.json 文件
• swagger ui 正确重定向到它

使用方法

composer require goopil/yml-swagger-l5

对于 laravel < 5.5

将 Goopil\YmlSwagger\YmlSwaggerProvider 添加到 config/app.php

资源

• 所有：php artisan vendor:publish --provider=Goopil\YmlSwagger\YmlSwaggerProvider
• 仅配置：php artisan vendor:publish --provider=Goopil\YmlSwagger\YmlSwaggerProvider --tag=config

调整配置

通常我会添加以下结构来定义我的端点

• route/swagger/dto 用于定义模型（DTO 作为数据传输对象）
• route/swagger/api 用于定义端点。

您可以在文件之间添加引用，因为所有 yml 文件在服务之前都会被连接

示例

用户 DTO

route/swagger/dto/user.yml

definitions:

  NewUser:
    type: object
    required:
      - username
      - email
      - password
    properties:
      username:
        type: string
      email:
        type: string
      password:
        type: string
        format: password

  UpdateUser:
    type: object
    properties:
      username:
        type: string

  User:
    allOf:
      - $ref: '#/definitions/NewUser'
      - type: object
        properties:
         id:
           type: uint
           readOnly: true
         created_at:
           type: string
           format: date-time
           readOnly: true
         updated_at:
           type: string
           format: date-time
           readOnly: true

用户展示端点 route/swagger/api/user.yml

paths:
  /users/{id}:
    get:
      tags:
      - Users
      operationId: userShow
      security:
      - JWT: []
      parameters:
      - name: id
      in: path
      type: string
      responses:
        200:
          description: Requested User
          schema:
            $ref: '#/definitions/User'

贡献

欢迎从错误报告到新想法的所有贡献，当然也包括合并请求。