| 1 | {"openapi":"3.0.0","info":{"contact":{"x-twitter":"stoplightio"},"title":"Stoplight","version":"api-v1","x-apisguru-categories":["developer_tools"],"x-logo":{"url":"https://twitter.com/stoplightio/profile_image?size=original"},"x-origin":[{"format":"swagger","url":"https://api.stoplight.io/v1/versions/wDcMCTKXwn8X4ynL9/export/oas.json","version":"2.0"}],"x-providerName":"stoplight.io"},"paths":{"/versions/publish/anon":{"post":{"description":"Anonymously publish to API Docs.\n\nThis endpoint will take a JSON spec or a URL to a swagger or raml spec.\n\n```\n{\n \"specData\": {...}\n}\n```\n\nor\n\n```\n{\n \"url\": \"http://petstore.swagger.io/v2/swagger.json\"\n}\n```\n\nThe spec will be published to api-docs.io anonymously, which means you will not be able to update or remove this documentation.\n\nThe response will contain a url to the published documentation.\n\n```\n{\n \"url\": \"https://swagger-petstore.api-docs.io/v1.0.0\"\n}\n```\n\n\nThe limitations of anonymous publishing\n* Cannot update/remove the documentation\n* Cannot choose the subdomain\n* Cannot choose the version\n* Cannot add theming","operationId":"POST_versions-publish-anon","requestBody":{"content":{"application/json":{"schema":{"properties":{"specData":{"oneOf":[{"type":"object"},{"type":"string"}]},"url":{"type":"string"}},"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"url":{"type":"string"}},"required":["url"],"type":"object"},"examples":{"response":{"value":{"url":"https://stoplight.api-docs.io/api-v1"}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"500":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}}},"summary":"Publish Anonymous"}},"/versions/{versionId}/export/{format}":{"get":{"description":"Export a version to your choice of API specification.\n\n### Allowed Formats:\n\n- oas.json\n- oas.yaml\n- raml08.yaml\n- raml10.yaml\n- stoplight.json\n- stoplight.yaml\n\nThe stoplight format actually returns OAS (Swagger 2) with x-stoplight annotations. If you are exporting with the intent on importing back into Stoplight, this export format preserves the most information.\n\n### Example URL:\n\n`https://api.stoplight.io/v1/versions/123/export/oas.json`","operationId":"GET_versions-versionId-export-format","responses":{"200":{"description":"","content":{"text/yaml":{"schema":{"description":"The specification. Returned as a string when YAML, object when JSON.","oneOf":[{"type":"object"},{"type":"string"}]}},"application/json":{"examples":{"response":{"value":{"info":{"title":"Test API","version":"1.0"},"paths":{},"swagger":"2.0"}}}}}},"401":{"$ref":"#/components/responses/trait_standardErrors_401"},"404":{"$ref":"#/components/responses/trait_standardErrors_404"}},"summary":"Export","tags":["Versions"]},"parameters":[{"description":"This is the unique identifier for the version.","in":"path","name":"versionId","required":true,"schema":{"type":"string","default":""}},{"description":"The specification / format that you want to export.","in":"path","name":"format","required":true,"schema":{"type":"string","enum":["oas.json","oas.yaml","raml08.yaml","raml10.yaml","stoplight.json","stoplight.yaml"],"default":"oas.json"}}]},"/versions/{versionId}/import":{"parameters":[{"description":"This is the unique identifier for the version.","in":"path","name":"versionId","required":true,"schema":{"type":"string"}}],"put":{"description":"Import the given specification into an existing version. \n\n**Warning, this is a destructive action! Any resources present in both the existing version, and the specification being imported, will be overwritten.**\n\nThis endpoint is particularly useful when you manage a specification file (Swagger or RAML) outside of Stoplight, and want to keep your Stoplight API version up to date as that specification changes.\n\nBy default, a \"merge\" is performed when importing. If a resource exists in the specification that you are importing, and in the Stoplight API, the resource will be overwritten. If a resource exists in the Stoplight API, but not in the spefication that you are importing, the resource will be left alone (and not deleted).\n\nYou can include an optional `options` property in the request body, to indicate if you would like to perform more of a replacement (instead of a merge). The options are documented in full in the response definition below these notes.\n\nTake this request + request body for example:\n\n`PUT https://api.stoplight.io/v1/versions/123/import`\n```json\n{\n \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n \"options\": {\n \"removeExtraEndpoints\": true,\n \"removeExtraSchemas\": true\n }\n}\n```\n\nThis request will grab the swagger specification described at `http://petstore.swagger.io/v2/swagger.json`, and import it into the Stoplight API version with id `123`. Additionally, it will delete any existing endpoints or models that are not described in the petstore swagger being imported.\n\nInstead of a URL, you can provide the actual specification to be imported, either as a string (in the case of YAML) or an object (in the case of JSON). That request would look something like this:\n\n`PUT https://api.stoplight.io/v1/versions/123/import`\n```json\n{\n \"specData\": {\n \"swagger\": \"2.0\",\n \"info\": {}\n ... rest of spec\n }\n}\n```","operationId":"PUT_versions-versionId-import","requestBody":{"content":{"application/json":{"schema":{"example":{"options":{"removeExtraEndpoints":true,"removeExtraModels":true},"url":"http://petstore.swagger.io/v2/swagger.json"},"properties":{"options":{"properties":{"removeExtraEndpoints":{"description":"Default: false.","type":"boolean"},"removeExtraSchemas":{"description":"Default: false.","type":"boolean"},"removeExtraTextSections":{"description":"Default: false.","type":"boolean"},"removeExtraTraits":{"description":"Default: false.","type":"boolean"}},"type":"object"},"specData":{"oneOf":[{"type":"object"},{"type":"string"}]},"url":{"type":"string"}},"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"endpointCount":{"type":"number"},"format":{"enum":["RAML08","RAML10","SWAGGER","STOPLIGHTX"],"type":"string"},"projectId":{"type":"string"},"schemaCount":{"type":"number"},"testCount":{"type":"number"},"textSectionCount":{"type":"number"},"traitCount":{"type":"number"},"versionId":{"type":"string"},"workspaceId":{"type":"string"}},"required":["workspaceId","projectId","versionId","schemaCount","textSectionCount","traitCount","endpointCount","testCount","format"],"type":"object"}},"required":["data"],"type":"object"}}}},"401":{"$ref":"#/components/responses/trait_standardErrors_401"},"404":{"$ref":"#/components/responses/trait_standardErrors_404"}},"security":[{"Authorization":[]}],"summary":"Import","tags":["Versions"]}},"/versions/{versionId}/publish":{"parameters":[{"description":"This is the unique identifier for the version.","in":"path","name":"versionId","required":true,"schema":{"type":"string"}}],"post":{"description":"Re-publish an API version in Stoplight. This will re-publish the given API version, with whatever publish settings have already been setup in the app.\n\nThis will only work with APIs that have previously been published at least once.\n\nThis works well with the #endpoint:957qEfc97BB5XGAeZ endpoint to augment your continuous integration processes, and automatically re-publish your documentation when certain events happen. Once such scenario is:\n\n1. Swagger is generated from your codebase, and pushed up to Github.\n2. A simple script that you write sends a request to the Stoplight API to import the new specification, passing in the URL to the swagger file on Github.\n3. After the import succeeds, and your API in Stoplight is up to date, the script sends a request to the Stoplight API (this endpoint) to re-publish your documentation.","operationId":"POST_versions-versionId-publish","responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"customDomain":{"type":"string"},"url":{"type":"string"}},"required":["url"],"type":"object"},"examples":{"response":{"value":{"customDomain":"https://help.stoplight.io/api-v1","url":"https://stoplight.api-docs.io/api-v1"}}}}}},"401":{"$ref":"#/components/responses/trait_standardErrors_401"},"404":{"$ref":"#/components/responses/trait_standardErrors_404"}},"security":[{"Authorization":[]}],"summary":"Publish","tags":["Versions"]}},"/versions/{versionId}/unpublish":{"parameters":[{"description":"This is the unique identifier for the version.","in":"path","name":"versionId","required":true,"schema":{"type":"string"}}],"put":{"description":"Unpublish the documentation associated with the given API version.","operationId":"PUT_versions-versionId-unpublish","responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"object"}},"type":"object"},"examples":{"response":{"value":{"data":{}}}}}}},"401":{"$ref":"#/components/responses/trait_standardErrors_401"},"404":{"$ref":"#/components/responses/trait_standardErrors_404"}},"security":[{"Authorization":[]}],"summary":"Unpublish","tags":["Versions"]}}},"servers":[{"url":"https://api.stoplight.io/v1"}],"components":{"responses":{"trait_standardErrors_400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"trait_standardErrors_401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"trait_standardErrors_404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}},"trait_standardErrors_500":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standarderror"}}}}},"securitySchemes":{"Authorization":{"in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"shared-user":{"properties":{"":{"type":"string"},"username":{"type":"string"}},"title":"Shared User","type":"object"},"standarderror":{}}}} |