Upgrade Stoplight Format As Swagger-Extension

[ranacseruet]

Current stoplight format is a raw independent format, only applicable/compatible with stoplight platform itself. This feature will help maintaining stoplight format as an swagger-extension format.

This will always be compatible anywhere swagger is supported and additionally, can be imported to stoplight platform with stoplight specific fields/attributes as well.

Here are the list of fields those need to be taken care of in swagger-extension(stoplight) format in addition to what are already supported:

Environment:
    - middlewareBefore
    - middlewareAfter
    - proxy

Endpoint:
    - _id
    - middlewareBefore
    - middlewareAfter
    - mock

utilityFunctions:
   -Everything

resourcesOrder:
   -Everything

[ranacseruet]

@marbemac , feel free to review when you have a moment and add anything you think might be missing.

[marbemac]

I think that's most of it. A while back, either in slack or TP, we were sending around swagger specs w stoplight extensions. Think you could dig up the one we decided on in the end? I think that has everything in it, plus naming and organization.

[ranacseruet]

Sure, here is the example format you came up with as I found on slack. Adding it here for reference:

{
  "swagger": "2.0",
  "host": "http://localhost:3000",  
  "basePath": "",
  "info": {
    "version": "",
    "title": "TODO",
    "description": "# Welcome\n\nThis is a place to put general notes and extra information about your project / API.\n\nClick on the edit icon in the top left to change this content.\n\nCheck out the video below, or get started right away by choosing an environment from the list\non the left.\n\n::: meta\n  ### Tips\n\n  You can use the meta markdown directive to add sidebar content (on large screens).\n\n  ### Useful Links\n  - [Getting Started](/docs/designer/#getting-started)\n  - [Markdown Reference](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)\n  - [StopLight Markdown Directives](/docs/designer/#markdown)\n:::\n\n@[vimeo](147427619)\n\n# Section 2\n\nH1 titles automatically create new sections.\n\n::: meta\n  Meta content gets put into the sidebar of its parent section.\n:::"
  },
  "paths": {
    "/api/task_lists": {
      "parameters": [],
      "get": {
        "responses": {},
        "parameters": [],
        "consumes": [
          "application/json"
        ],
        "produces": [],
        "operationId": "",
        "summary": "",
        "description": ""
        "x-stoplight-before": "function (ctx, request) {\n  // For example, adding ?mock=200 to a request url will enable mocking,\n  // using the example endpoint response for the 200 status code.\n  var mock = request.url.query.get(\"mock\")\n  if (mock) {\n    ctx.mock.set(true, mock)\n  }\n}",
        "x-stoplight-after": "function (ctx, request) {\n  // For example, adding ?mock=200 to a request url will enable mocking,\n  // using the example endpoint response for the 200 status code.\n  var mock = request.url.query.get(\"mock\")\n  if (mock) {\n    ctx.mock.set(true, mock)\n  }\n}",
        "x-stoplight-mock": false
      }
    }
  },
  "definitions": {},
  "x-stoplight": {
    "before": "function(ctx, request) {\n  // This runs your endpoint middleware before script, if applicable.\n  // Removing this means your endpoint before scripts will not be run!\n  SL.runEndpoint();\n}",
    "after": "function(ctx, request, response) {\n  // This runs your endpoint middleware after script, if applicable.\n  // Removing this means your endpoint after scripts will not be run!\n  SL.runEndpoint();\n}",
    "proxy": {
      "port": "4010",
      "startupMessage": "",
      "log": true,
      "learn": false,
      "mock": false,
      "debug": true
    }
    "functions": [
      {
        "name": "queryStringMocking",
        "description": "This extends the basic mocking functionality, and makes it possible to control mocking behavior via the request query string.",
        "script": "function (ctx, request) {\n  // For example, adding ?mock=200 to a request url will enable mocking,\n  // using the example endpoint response for the 200 status code.\n  var mock = request.url.query.get(\"mock\")\n  if (mock) {\n    ctx.mock.set(true, mock)\n  }\n}"
      },
      {
        "name": "onlyProcessPath",
        "description": "If your API lives at a subpath, for example, localhost:3000/api, then this function is useful to only learn / log requests that match the given subpath.",
        "script": "function (ctx, request, subpath) {\n  // for example, onlyProcessPath(ctx, request, \"api\") will turn off logging/learning for any\n  // requests that don't have \"api\" in their path.\n  if (request.url.path.get().indexOf(subpath) == -1) {\n     ctx.log.set(false)\n     ctx.learn.set(false)\n  }\n}"
      },
      {
        "name": "addRandomLatency",
        "description": "Sleep for a random amount of time. Useful to simulate latency.",
        "script": "function (min, max) {\n  SL.sleep(SL.rand(min, max))\n}"
      },
      {
        "name": "validateResponse",
        "description": "Calling this function will validate the response.",
        "script": "function (ctx, response) {\n  var messages = response.validate();\n      \n  if (!response.valid.get()) {\n    // If mocking is enabled and validation fails, this means \n    // the example mock we've set for this endpoint/status code \n    // does not match the schema.. we don't want developers working \n    // off of an invalid example, so here we ovewrite the response\n    // with the the validation error messages.\n    if (ctx.mock.enabled.get()) {\n      response.body.set(messages)\n    }\n  }\n}"
      },
      {
        "name": "validateRequest",
        "description": "Calling this function will validate the request. Uncomment the line indicated in the script to add helpful validation errors to your api calls.",
        "script": "function (ctx, request) {\n  var messages = request.validate();\n  \n  if (!request.valid.get()) {\n    // Uncomment the line below to respond immediately\n    // with the validation error messages. Useful to let\n    // developers know exactly what is wrong with their API request.\n\n    // request.hijack(400, \"application/json\", messages)\n  }\n}"
      }
    ],
    "groupings": {
      "endpoints": []
    }
  }
}

[marbemac]

what do you think? anything missing or need to be re-considered?

[ranacseruet]

Sounds OK to me. Apparently, don't see a problem atm. I will let you know if something come up in the way.

[ranacseruet]

@marbemac , I have updated this package version on our app, which will include this feature (along with oauth2 security updates as well).

I also have re-enabled import/export option for stoplight as well. Seems to be working for me. Please verify from your side.

[ranacseruet]

This is already done. Closing it.