Swagga

{
    "swagger":     "2.0",
    "info":        {
        "title":   "API",
        "version": "0.2"
    },
    "host":        "xxx.yy.z",
    "basePath":    "/api",
    "schemes":     [
        "https"
    ],
    "tags":        [
        {
            "name":        "users",
            "description": "Actions involving users"
        }
    ],
    "parameters":  {
        "userIdParam": {
            "name":        "id",
            "in":          "path",
            "description": "User id",
            "required":    "true",
            "type":        "integer",
            "format":      "int64"
        }
    },
    "definitions": {
        "user": {
            "type":       "object",
            "properties": {
                "user_id":         {
                    "type":        "integer",
                    "description": "User ID.",
                    "example":     55
                },
                "user_name_first": {
                    "type":        "string",
                    "description": "User's first name",
                    "example":     "Jan "
                },
                "user_name_last":  {
                    "type":        "string",
                    "description": "User's last name",
                    "example":     "Nowak"
                }
            }
        }
    },
    "paths":       {
        "/users/{id}": {
            "get": {
                "tags":       [
                    "users"
                ],
                "summary":    "Returns user data specified by user ID",
                "parameters": [
                    {
                        "$ref": "#/parameters/userIdParam"
                    }
                ],
                "responses":  {
                    "200": {
                        "description": "Single user details",
                        "schema":      {
                            "type":       "object",
                            "properties": {
                                "data":    {
                                    "$ref": "#/definitions/user"
                                },
                                "code":    {
                                    "type":        "string",
                                    "description": "Response code",
                                    "example":     "200"
                                },
                                "success": {
                                    "type":        "boolean",
                                    "description": "Operation status",
                                    "example":     true
                                },
                                "type":    {
                                    "type":        "string",
                                    "description": "Action type",
                                    "example":     "Users"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}