Swagger Docs Generator

This is a documentation generator for swagger-ui. It will scan your project source code, extract the comment with special beginning, parse the swagger code within the comment and generate the swagger documentation.

3 Steps to use the swagger docs generator

Documentation: write the swagger doc for your project
Configuration: specify the project root path, your api url and swagger doc url in the config.json
Run & Export: run the doc generator and copy all the generated docs to location that can be directly accessed by the swagger doc url defined in step 2 and modify the swagger-ui's index.html file

1 Documentation

All the swagger doc should be place within the comment started with /**

Resource

One resource could contain any number of APIs

/**
 * @resource /path
 */

@resource: the relative path of the API

Generated Swagger doc would be:

{
    "resource": ${/path},
    ...
}

API

/**
  * @api apiName
  *
  * @desc (short description of the api)
  *
  * @url /relative/path/to/api/root/url
  *
  * @method httpMethod
  *
  * @param type name [restriction.] [description of the param]
  *
  * @status statusCode (reason why the occuried)
  *
  * @return returnType
  */

@api: Name for the API

syntax: @api apiName
noted: the apiName is a one-word name

@desc: Description for the API

syntax: @desc short description of this API

@url: The relative url based on the API root url which will be stated in Step 2

syntax: @url /relative/path/to/api/root/url
Optional path parameter
- Since the swagger doesn't support optional path parameter, If you need it. Use the swagger-ui I forked.
- syntax: /url/contain(/{optional})

@method: the http method of the request

syntax: @method httpMethod
noted: the valid HTTP method included GET, POST, PUT and HEAD

@param: the parameter sent with the request

syntax @param type name [restriction.] [description of the param]
- type: the data type of the parameter.
- name: the name of the parameter. can be ommited if its type is not primitive
- restriction (optional): the restriction of the parameter.
  - syntax: restriction1, restriction2 .
  - noted: the restriction must split by comma (,) and stoped by fullstop (.)
  - valid restriction are required and multiple

The generated Swagger doc would be

@param string foo required. foo description
{
    "dataType": "string",
    "name": "foo",
    "required": true,
    "allowMultiple": false,
    "paramType": ${auto generated},
    "description": "foo description"
}

@status: the response status of the API

syntax @status statusCode reason why the occuried
- statusCode: the status code of the response such as 200, 404
- reason: a text description of the reason why such code occuried

@return the response type

noted: the response type could be array
syntax: LIST[type]

Generated Swagger doc would be:

{
    "path": ${/relative/path/to/api/root/url},
     "operations": [
         {
             "nickname": ${apiName},
             "httpMethod": ${httpMethod},
             "notes": ${short description of the api},
             "responseClass": ${returnType},
             "parameters": [
                {
                    "dataType": ${type},
                    "name": ${name},
                    "required": ${is required restriction stated},
                    "allowMultiple": ${is multiple restriction stated},
                    "paramType": ${auto generated},
                    "description": ${description}
                }
             ],
             "errorResponses": [
                 {
                     "code": ${statusCode},
                     "reason": ${reason why the occuried}
                 }
             ]
         }
     ]
}

Model

One model might contain any number of properties

/**
 * @model modelName
 */

@model:

syntax @model modelName
noted: the modelName is a one-word name

Generated Swagger doc would be:

${modelName}: {
    "id": ${modelName}
    ...
}

Property

/**
 * @property name:type description
 */

@property: the property of the model

syntax: @property name:type description
- name: the name of the property
- type: the type of the property could be one of the following three
  - normal: a primitive or complex type
  - range type:
    - syntax: min-max
    - noted: min is the lower bound of the range while max is the upper bound. no space within the expression
  - list type (or enum):
    - syntax: primitiveType(enum1|enum2|emun3)
    - noted all the enums must be splited by |.
- description of the property

Generated Swagger doc would be:

# 1 normal type
# @property name:type description
#
"properties": {
    ${name}: {
        "type": ${type},
        "description": ${description}
    }
    ...
}

# 2. enums
# @property name:type(enum1|enum2|enum3) description
#
"properties": {
    ${name}: {
        "type": ${type}
        "description": ${description},
        "allowableValues":{
          "valueType":"LIST",
          "values":[
            ${enum1},
            ${enum2},
            ${enum3}
          ]
        }
    }
    ...
}

# 3. range
# @property name:1-10 description
#
"properties": {
    ${name}: {
        "type": ${type}
        "description": ${description},
        "allowableValues": {
          "valueType": "RANGE",
          "min": ${min},
          "max": ${max}
        }
    }
    ...
}

2 Configuration

config.js

{
    "discoverPath" : [
        "project/dir/path/to/scan"
    ],
    "outputDir" : "dir/path/to/output",
    "excludedPath" : [
        "dir/path/not/to/scan"
    ],
    "apiVersion": "[api version]",
    "swaggerVersion": "1.0",
    "basePath" : "[your api root url]",
    "resourceListPath" : "[your swagger doc url]",
    "templatePath": "template.json"
}

The configuration is placed in the config.json file.

discoverPath: state the project directories want to be scaned. \
outputDir: all the generated swagger docs will be placed to this directory.
excludedPath: the path you don't want the program to scan.
apiVersion: the api version
swaggerVersion: the swagger version. we use 1.0 now
basePath: the api root url
resourceListPath: the swagger doc url which can be accessed by internet
templatePath: the template configuration for the interpreter.

All the fields are required.

3 Run & Export

Run the swagger-php-cli.php program

$ php swagger-php-cli.php

All the swagger docs will be placed to the outputDir directory stated in the config file. Move to the resouceListPath your stated in the config file.

Modify the index.html file of the swagger-ui. Make its discover path point to the url of your location of api-docs.json

Samples

the sample folder contain a set of comprehensive samples.

############# SampleAPI.php
<?php
/**
 * @resource /sampleAPI
 */
class SampleAPI {
    /**
     * @api api1
     *
     * @url /sampleAPI/api1
     *
     * @desc this is a foo API
     *
     * @method POST
     *
     * @param SampleModel required. this is a bar
     *
     * @return SampleModel(sample:SampleModel)
     */
    public function api1() { }
    /**
     * @api api2
     *
     * @url /sampleAPI/api2
     *
     * @desc this is a foo API
     *
     * @method GET
     *
     * @param int foo required, multiple. this is a foo
     *
     * @return LIST[SampleModel]
     */
    public function api2() { }
}

############# SampleModel.php
<?php

/**
 * @model SampleModel
 */
class SampleModel {
    /**
     * @property id:string the id
     */
    public $id;

    /**
     * @property range:1-100 the valid range is from 1-100
     */
    public $range;

    /**
     * @property enum:string(enum1|enum2|enum3)
     */
    public $enum;

    /**
     * @property sample:string
     */
    public $sample;
}

############# Generated Swagger doc
{
    "resource": "\/sampleAPI",
    "basePath": "http:\/\/foo.com",
    "apiVersion": "1.0",
    "swaggerVersion": "1.0",
    "apis": [
        {
            "path": "\/sampleAPI\/api1",
            "operations": [
                {
                    "nickname": "api1",
                    "notes": "this is a foo API",
                    "httpMethod": "POST",
                    "responseClass": "SampleModel(sample:SampleModel)",
                    "parameters": [
                        {
                            "dataType": "SampleModel",
                            "name": "SampleModel",
                            "required": true,
                            "allowMultiple": false,
                            "paramType": "body",
                            "description": " this is a bar"
                        }
                    ]
                }
            ]
        },
        {
            "path": "\/sampleAPI\/api2",
            "operations": [
                {
                    "nickname": "api2",
                    "notes": "this is a foo API",
                    "httpMethod": "GET",
                    "responseClass": "LIST[SampleModel]",
                    "parameters": [
                        {
                            "dataType": "int",
                            "name": "foo",
                            "required": true,
                            "allowMultiple": true,
                            "paramType": "query",
                            "description": " this is a foo"
                        }
                    ]
                }
            ]
        }
    ],
    "models": {
        "SampleModel(sample:SampleModel)": {
            "id": "SampleModel(sample:SampleModel)",
            "properties": {
                "id": {
                    "type": "string"
                },
                "range": {
                    "type": "int",
                    "allowValues": {
                        "valueType": "RANGE",
                        "max": 100,
                        "min": 1
                    }
                },
                "enum": {
                    "type": "string",
                    "allowValues": {
                        "valueType": "LIST",
                        "values": [
                            "num1",
                            "enum2",
                            "enum3"
                        ]
                    }
                },
                "sample": {
                    "type": "SampleModel"
                }
            }
        },
        "SampleModel": {
            "id": "SampleModel",
            "properties": {
                "id": {
                    "type": "string"
                },
                "range": {
                    "type": "int",
                    "allowValues": {
                        "valueType": "RANGE",
                        "max": 100,
                        "min": 1
                    }
                },
                "enum": {
                    "type": "string",
                    "allowValues": {
                        "valueType": "LIST",
                        "values": [
                            "num1",
                            "enum2",
                            "enum3"
                        ]
                    }
                },
                "sample": {
                    "type": "string"
                }
            }
        }
    }
}

the inline_sample folder give a example for the inline style swagger annotation

<?php
class InlineStyleSample {
    /**
     * @resource /inlineStyle
     *
     * @api foofoo
     *
     * @url /foo/foofoo
     *
     * @desc this is a foo API
     *
     * @method POST
     *
     * @param Bar required. this is a bar
     *
     * @return BarBar(bar:Bar)
     *
     * @model Bar
     *
     * @property barbar:BarBar barbarbar
     *
     * @model BarBar
     *
     * @property bar:string barbabrabrbarb ab
     *
     */
    public function foofoo($Bar) {

    }
}

## Generated Swagger Docs
{
    "resource": "\/inlineStyle",
    "basePath": "http:\/\/foo.com",
    "apiVersion": "1.0",
    "swaggerVersion": "1.0",
    "apis": [
        {
            "path": "\/foo\/foofoo",
            "operations": [
                {
                    "nickname": "foofoo",
                    "notes": "this is a foo API",
                    "httpMethod": "POST",
                    "responseClass": "BarBar(bar:Bar)",
                    "parameters": [
                        {
                            "dataType": "Bar",
                            "name": "Bar",
                            "required": true,
                            "allowMultiple": false,
                            "paramType": "body",
                            "description": " this is a bar"
                        }
                    ]
                }
            ]
        }
    ],
    "models": {
        "BarBar(bar:Bar)": {
            "id": "BarBar(bar:Bar)",
            "properties": {
                "bar": {
                    "type": "Bar"
                }
            }
        },
        "Bar": {
            "id": "Bar",
            "properties": {
                "barbar": {
                    "type": "BarBar"
                }
            }
        },
        "BarBar": {
            "id": "BarBar",
            "properties": {
                "bar": {
                    "type": "string"
                }
            }
        }
    }
}

Feature in Beta

Support model creation

For example:

# Create two model Foo and Bar
/**
 * @model Foo
 *
 * @property id:string
 * @property bar:string
 *
 * @model Bar
 *
 * @property bid:int
 */

# Within some APIs
/**
 * ...
 * @return Foo(bar:Bar)
 */

 In this case a new mode Foo(bar:Bar) is created. Its propotype as follow:
 /**
  * @model Foo(bar:Bar)
  *
  * @property id:string
  * @property bar:Bar
  */

limitation:

can only be applied to @return so far
the the type must be normal type. Foo(bar:Array[Bar]) is not supported yet

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
Configuration		Configuration
DocsGener		DocsGener
Interpreter		Interpreter
Utility		Utility
samples		samples
SwaggerGener.php		SwaggerGener.php
config.json		config.json
config.json.sample		config.json.sample
readme.md		readme.md
swagger-php-cli.php		swagger-php-cli.php
template.json		template.json

FinalBuild-Stidio/swagger-docsgen

Folders and files

Latest commit

History

Repository files navigation

Swagger Docs Generator

3 Steps to use the swagger docs generator

1 Documentation

Resource

API

Model

Property

2 Configuration

config.js

3 Run & Export

Samples

Feature in Beta

About

Resources

Stars

Watchers

Forks

Languages