php框架YII2的swagger踩坑记录

1. light/yii2-swagger 使用的YII框架这个包。（能不能拉下来，就得看你了，反正我是拉了很久）（默认是swagger3.0，与下面的demo不符合，下面的demo是用的2.0）由于我使用的工具只支持2.0，所以用2.0了，3.0变成了openapi规范了。

2. 开始可以先试用一下文档下面的demo

搭成功后， 他有个demo.gif，用cli启动命令，然后

然后在浏览器中输入：http://127.0.0.1:8080 就可以访问demo里面的接口对应的文档了。

（如果页面显示你要auth验证的话，你就把SiteController第58行.api_key 为 test 注释掉就可以了 ）

    3.我主要是想要生成json文件导入到其他工具使用。（其他方式需要在代码中配置）

在项目根目录

php vendor/zircote/swagger-php/bin/swagger ./modules/v1/controllers/ -o ./
第一个路径是执行文件，第二个路径是你写了注释的PHP文件，第三个是你生成swagerr.json的路径

生成后，大概是长成这样。

{
    "swagger": "2.0",
    "paths": {
        "/users": {
            "get": {
                "tags": [
                    "user"
                ],
                "summary": "\u83b7\u53d6\u7528\u6237\u5217\u8868",
                "description": "\u6d4b\u8bd5\u76f4\u63a5\u8fd4\u56de\u4e00\u4e2aarray",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "access_token",
                        "in": "query",
                        "description": "access token6666666666",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": " success"
                    }
                }
            },
            "post": {
                "tags": [
                    "user"
                ],
                "summary": "\u521b\u5efa\u7528\u6237\u63a5\u53e3",
                "description": "\u6d4b\u8bd5Param\u662f *query* \u7c7b\u578b, \u5982\u679c\u8bbe\u7f6e\u6210 *formData* \u7c7b\u578b\u7684\u5c31\u53ef\u4ee5\u4f7f\u7528post\u83b7\u53d6\u6570\u636e",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "username",
                        "in": "formData",
                        "description": "\u7528\u6237\u59d3\u540d",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "phone",
                        "in": "formData",
                        "description": "\u624b\u673a\u53f7",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "sex",
                        "in": "formData",
                        "description": "\u6027\u522b 1. \u7537 2.\u5973 \u6b64\u9879\u4e3a\u975e\u5fc5\u586b\u9879.\u5c55\u793a\u6210select",
                        "required": false,
                        "type": "integer",
                        "enum": [
                            1,
                            2
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": " success"
                    },
                    "401": {
                        "description": "\u9700\u8981\u91cd\u65b0\u767b\u9646",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            },
            "options": {
                "tags": [
                    "user"
                ],
                "summary": "options",
                "operationId": "userOptions",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "success",
                        "headers": {
                            "Allow": {
                                "type": "GET, POST, HEAD, OPTIONS"
                            },
                            "Content-Type": {
                                "type": "application/json; charset=UTF-8"
                            }
                        }
                    }
                }
            }
        },
        "/users/{id}": {
            "put": {
                "tags": [
                    "user"
                ],
                "summary": "\u66f4\u65b0\u7528\u6237\u63a5\u53e3",
                "description": "*path*\u7c7b\u578b\u7684\u53c2\u6570\u4f1a\u653e\u5165\u8bf7\u6c42\u5730\u5740\u5730\u5740\u4e2d",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "\u7528\u6237ID",
                        "required": true,
                        "type": "integer"
                    },
                    {
                        "name": "username",
                        "in": "formData",
                        "description": "\u7528\u6237\u59d3\u540d",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "phone",
                        "in": "formData",
                        "description": "\u624b\u673a\u53f7",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "sex",
                        "in": "formData",
                        "description": "\u6027\u522b 1. \u7537 2.\u5973 \u6b64\u9879\u4e3a\u975e\u5fc5\u586b\u9879.\u8fd9\u91cc\u6307\u5b9a\u4e86\u4e00\u4e2a\u9ed8\u8ba4\u9879\uff0c\u90a3\u4e48\u4f1a\u9ed8\u8ba4\u9009\u4e2d",
                        "required": false,
                        "type": "integer",
                        "default": 1,
                        "enum": [
                            1,
                            2
                        ]
                    },
                    {
                        "name": "job",
                        "in": "formData",
                        "description": "\u8fd9\u91cc\u53ef\u4ee5\u8bbe\u7f6e\u9ed8\u8ba4\u503c",
                        "required": false,
                        "type": "string",
                        "default": "\u7a0b\u5e8f\u733f"
                    },
                    {
                        "name": "avatar",
                        "in": "formData",
                        "description": "\u7c7b\u578b\u8bbe\u7f6e\u4e3a`file`\u5219\u53ef\u4ee5\u5c55\u793a\u4e0a\u4f20\u6309\u94ae\uff0c\u5728\u540e\u7aef\u548c\u666e\u901a\u4e0a\u4f20\u4e00\u6837\u5904\u7406",
                        "required": false,
                        "type": "file"
                    }
                ],
                "responses": {
                    "200": {
                        "description": " success"
                    },
                    "401": {
                        "description": "\u9700\u8981\u91cd\u65b0\u767b\u9646",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/users/query": {
            "post": {
                "tags": [
                    "user"
                ],
                "summary": "\u5220\u9664\u7528\u6237",
                "description": "\u8fd9\u91cc\u5c55\u793a\u4e00\u4e2a\u7a0d\u5fae\u9ad8\u7aef\u70b9\u7684\u7528\u6cd5",
                "operationId": "QueryUser",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "description": "\u8fd9\u91cc\u8981\u4e3b\u8981\u914d\u7f6e`request`\u7ec4\u4ef6\u7684parsers\uff0c\u6765\u652f\u6301\u63a5\u6536\u8fd9\u4e2a\u7c7b\u578b\u7684\u8bf7\u6c42",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/UserIdList"
                        },
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "success"
                    }
                }
            }
        }
    },
    "definitions": {}
}

 swagger3.0的生成文件长这样

openapi: 3.0.0
paths:
  /pets:
    get:
      description: 'Returns all pets from the system that the user has access to'
      operationId: findPets
      parameters:
        -
          name: tags
          in: query
          description: 'tags to filter by'
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
        -
          name: limit
          in: query
          description: 'maximum number of results to return'
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: 'pet response'
          content:
            text/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
            text/html:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        default:
          description: 'unexpected error'
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/ErrorModel'
            text/html:
              schema:
                $ref: '#/components/schemas/ErrorModel'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorModel'

 

可以参考的其他人和一些资料链接：

https://www.jianshu.com/p/554cd3762ab1

https://www.cnblogs.com/jcydd/p/11455989.html

https://openapi-map.apihandyman.io/

https://huangwenchao.gitbooks.io/swagger/content/

 

 

PHP的资料是真的少。。。。插件也是。。。。

暂时更新到这个里吧。