Skip to content

Commit

Permalink
Merge pull request #367 from snyk/docs/automatic-api-docs-update
Browse files Browse the repository at this point in the history 
Generate API docs from spec
  • Loading branch information
@mikeromard
mikeromard authored Sep 18, 2024
2 parents d73487c + 4a50f5c commit 9920868
Show file tree
Hide file tree
Showing 3 changed files with 97 additions and 121 deletions.
187 changes: 67 additions & 120 deletions docs/.gitbook/assets/rest-spec.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2440,7 +2440,7 @@
],
"type": "object"
},
"CommonIssueModel": {
"CommonIssueModelVThree": {
"properties": {
"attributes": {
"properties": {
Expand Down Expand Up @@ -2471,98 +2471,14 @@
],
"type": "string"
},
"key": {
"description": "The Snyk vulnerability ID.",
"example": "SNYK-JAVA-COMFASTERXMLWOODSTOX-2928754",
"type": "string"
},
"problems": {
"items": {
"$ref": "#/components/schemas/Problem"
},
"type": "array"
},
"severities": {
"description": "The severity level of the vulnerability: ‘low’, ‘medium’, ‘high’ or ‘critical’.",
"items": {
"$ref": "#/components/schemas/Severity"
},
"type": "array"
},
"slots": {
"$ref": "#/components/schemas/Slots"
},
"title": {
"description": "A human-readable title for this issue.",
"example": "XML External Entity (XXE) Injection",
"type": "string"
},
"type": {
"description": "The issue type",
"example": "package_vulnerability",
"type": "string"
},
"updated_at": {
"description": "When the vulnerability information was last modified.",
"example": "2022-06-16T14:00:24.315507Z",
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"id": {
"description": "The Snyk ID of the vulnerability.",
"example": "SNYK-JAVA-COMFASTERXMLWOODSTOX-2928754",
"type": "string"
},
"type": {
"description": "The type of the REST resource. Always ‘issue’.",
"example": "issue",
"type": "string"
}
},
"type": "object"
},
"CommonIssueModelVTwo": {
"properties": {
"attributes": {
"properties": {
"coordinates": {
"items": {
"$ref": "#/components/schemas/CoordinateVTwo"
},
"type": "array"
},
"created_at": {
"example": "2022-06-16T13:51:13Z",
"format": "date-time",
"type": "string"
},
"description": {
"description": "A description of the issue in Markdown format",
"example": "## Overview\\n\\n\\nAffected versions of this package are vulnerable to XML External Entity (XXE) Injection.",
"type": "string"
},
"effective_severity_level": {
"description": "The type from enumeration of the issue’s severity level. This is usually set from the issue’s producer, but can be overridden by policies.",
"enum": [
"info",
"low",
"medium",
"high",
"critical"
],
"type": "string"
},
"problems": {
"items": {
"$ref": "#/components/schemas/Problem"
},
"type": "array"
},
"severities": {
"description": "The severity level of the vulnerability: ‘low’, ‘medium’, ‘high’ or ‘critical’.",
"description": "An array of dictionaries containing all known data related to the vulnerability",
"items": {
"$ref": "#/components/schemas/Severity"
},
Expand Down Expand Up @@ -2624,25 +2540,6 @@
"type": "string"
},
"Coordinate": {
"properties": {
"remedies": {
"items": {
"$ref": "#/components/schemas/Remedy"
},
"type": "array"
},
"representation": {
"description": "The affected versions of this vulnerability.",
"items": {
"example": "5.3.0",
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"CoordinateVTwo": {
"properties": {
"remedies": {
"items": {
Expand Down Expand Up @@ -3356,6 +3253,26 @@
},
"type": "object"
},
"ExploitDetails": {
"description": "Details about the exploits",
"properties": {
"maturity_levels": {
"description": "List of maturity levels",
"items": {
"$ref": "#/components/schemas/MaturityLevel"
},
"type": "array"
},
"sources": {
"description": "Sources for determining exploit maturity level, e.g., CISA, ExploitDB, Snyk.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"FilePosition": {
"properties": {
"column": {
Expand Down Expand Up @@ -4816,7 +4733,7 @@
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/CommonIssueModel"
"$ref": "#/components/schemas/CommonIssueModelVThree"
},
"type": "array"
},
Expand All @@ -4836,7 +4753,7 @@
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/CommonIssueModelVTwo"
"$ref": "#/components/schemas/CommonIssueModelVThree"
},
"type": "array"
},
Expand Down Expand Up @@ -4979,6 +4896,27 @@
},
"type": "object"
},
"MaturityLevel": {
"description": "Details about the maturity level",
"properties": {
"format": {
"description": "The standard by which the “maturity” value is shown.",
"example": "CVSSv4",
"type": "string"
},
"level": {
"description": "Exploit maturity of the vulnerability. For CVSSv3: Proof of Concept, Functional, High. For CVSSv4: Unreported, Proof of Concept, Attacked.",
"example": "Attacked",
"type": "string"
},
"type": {
"description": "Indicates if the CVSS item is primary or secondary. Clients should prefer the primary CVSS vector.",
"example": "primary",
"type": "string"
}
},
"type": "object"
},
"MemberRoleRelationship": {
"additionalProperties": false,
"nullable": true,
Expand Down Expand Up @@ -5736,12 +5674,12 @@
"properties": {
"name": {
"description": "The package’s name",
"example": "woodstox-core",
"example": "spring-core",
"type": "string"
},
"namespace": {
"description": "A name prefix, such as a maven group id or docker image owner",
"example": "com.fasterxml.woodstox",
"example": "org.springframework",
"type": "string"
},
"type": {
Expand All @@ -5756,7 +5694,7 @@
},
"version": {
"description": "The version of the package",
"example": "5.0.0",
"example": "1.0.0",
"type": "string"
}
},
Expand Down Expand Up @@ -7573,11 +7511,12 @@
"Severity": {
"properties": {
"level": {
"description": "Level of severity calculated via vector",
"example": "medium",
"type": "string"
},
"score": {
"description": "The CVSSv3 value of the vulnerability.",
"description": "The CVSS score calculated from the vector, representing the severity of the vulnerability on a scale from 0 to 10.",
"example": 5.3,
"nullable": true,
"type": "number"
Expand All @@ -7587,11 +7526,21 @@
"example": "Snyk",
"type": "string"
},
"type": {
"description": "Indicates if the CVSS item is primary or secondary. Clients should prefer the primary CVSS vector.",
"example": "primary",
"type": "string"
},
"vector": {
"description": "The CVSSv3 value of the vulnerability.",
"description": "CVSS vector string detailing the metrics of a vulnerability.",
"example": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L",
"nullable": true,
"type": "string"
},
"version": {
"description": "CVSS version being described.",
"example": "4.0",
"type": "string"
}
},
"type": "object"
Expand Down Expand Up @@ -7681,10 +7630,8 @@
"format": "date-time",
"type": "string"
},
"exploit": {
"description": "The exploit maturity. Value of ‘No Data’, ‘Not Defined’, ‘Unproven’, ‘Proof of Concept’, ‘Functional’ or ‘High’.",
"example": "Not Defined",
"type": "string"
"exploit_details": {
"$ref": "#/components/schemas/ExploitDetails"
},
"publication_time": {
"description": "The time at which this vulnerability was published.",
Expand Down Expand Up @@ -44900,9 +44847,9 @@
"2023-03-29~beta",
"2023-04-17",
"2023-08-21",
"2024-06-26~beta"
"2024-06-26"
],
"x-snyk-api-version": "2023-08-21"
"x-snyk-api-version": "2024-06-26"
},
"x-snyk-api-resource": "issues"
},
Expand Down Expand Up @@ -45001,9 +44948,9 @@
"x-snyk-api-releases": [
"2022-06-29~beta",
"2022-09-15",
"2024-06-26~beta"
"2024-06-26"
],
"x-snyk-api-version": "2022-09-15"
"x-snyk-api-version": "2024-06-26"
},
"x-snyk-api-resource": "issues"
},
Expand Down
29 changes: 29 additions & 0 deletions docs/snyk-api/rest-api/changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,32 @@
## 2024-09-04

### GET - `/orgs/{org_id}/packages/{purl}/issues` - Updated
- removed the optional property `data/items/attributes/coordinates/items/representation` from the response with the `200` status
![Badge](https://img.shields.io/badge/Breaking-yellow)
- removed the optional property `data/items/attributes/key` from the response with the `200` status
![Badge](https://img.shields.io/badge/Breaking-yellow)
- removed the optional property `data/items/attributes/slots/exploit` from the response with the `200` status
![Badge](https://img.shields.io/badge/Breaking-yellow)
- added the optional property `data/items/attributes/severities/items/type` to the response with the `200` status

- added the optional property `data/items/attributes/severities/items/version` to the response with the `200` status

- added the optional property `data/items/attributes/slots/exploit_details` to the response with the `200` status

- added the required property `data/items/attributes/coordinates/items/representations` to the response with the `200` status



### POST - `/orgs/{org_id}/packages/issues` - Updated
- removed the optional property `data/items/attributes/slots/exploit` from the response with the `200` status
![Badge](https://img.shields.io/badge/Breaking-yellow)
- added the optional property `data/items/attributes/severities/items/type` to the response with the `200` status

- added the optional property `data/items/attributes/severities/items/version` to the response with the `200` status

- added the optional property `data/items/attributes/slots/exploit_details` to the response with the `200` status


## 2024-08-25 - Updated 2024-09-11

### POST - `/orgs/{org_id}/apps` - Updated
Expand Down
2 changes: 1 addition & 1 deletion tools/api-docs-generator/sync-state.yml
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
lastSyncedVersion: "2024-08-25"
lastSyncedVersion: "2024-09-04"

0 comments on commit 9920868

Please sign in to comment.