From f9bc2546d27fddf4873e06d4503349952d062b48 Mon Sep 17 00:00:00 2001 From: Fleeym <61891787+Fleeym@users.noreply.github.com> Date: Thu, 15 Feb 2024 01:02:58 +0200 Subject: [PATCH] update readme and spec --- README.md | 8 +- openapi.yml | 358 ++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 253 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index c7d0ced..b88fba3 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,13 @@ WIP version of the new Geode Index, hosted on its own server rather than a Githu - [x] Mod adding and updating - [x] Dependencies -- [ ] Support for multiple developers per mod +- [x] Support for multiple developers per mod - [ ] Finish the openapi spec - [ ] Finish the database structure -- [ ] Github OAuth -- [ ] A token system for authenticating the CLI +- [x] Github OAuth +- [x] A token system for authenticating the CLI +- [ ] logo.png management +- [ ] Download counts If you want to contribute to this project, please do so! I have no bloody clue how to write a web server. diff --git a/openapi.yml b/openapi.yml index 7001d65..21ca8c5 100644 --- a/openapi.yml +++ b/openapi.yml @@ -1,15 +1,15 @@ -openapi: '3.1.0' +openapi: "3.1.0" info: title: Geode Index description: Documentation for the Geode Index API - version: '1.0.0' + version: "1.0.0" -tags: +tags: - name: mods - description: Access to Index mods + description: Access to Index mods - name: user - description: User management + description: User management paths: /mods: @@ -17,6 +17,7 @@ paths: tags: - mods summary: Search all mods, paginated + description: Returns a list of mods, paginated. Does not include about.md and changelog.md. Does not include dependencies and incompatibilities. parameters: - name: query @@ -33,26 +34,31 @@ paths: - name: platforms in: query description: Platforms that mods have to support, comma separated [win,android32,android64,mac,ios] - example: 'win,android32,android64' + example: "win,android32,android64" schema: type: string - - $ref: '#/components/parameters/GeodeVersionQuery' - - $ref: '#/components/parameters/Page' - - $ref: '#/components/parameters/PerPage' + - $ref: "#/components/parameters/GeodeVersionQuery" + - $ref: "#/components/parameters/Page" + - $ref: "#/components/parameters/PerPage" responses: - '200': + "200": description: OK content: - application/json: + application/json: schema: type: array items: $ref: "#/components/schemas/Mod" + "500": + $ref: "#/components/responses/InternalServerError" post: tags: - mods summary: Create a new mod + description: This endpoint is only used for adding a new mod. For creating a new version, use the POST /mods/{id}/versions endpoint. + security: + - bearerAuth: [] requestBody: content: @@ -66,164 +72,225 @@ paths: examples: - "https://github.com/geode-sdk/NodeIDs/releases/download/v1.0.0/geode.node-ids.geode" - "https://github.com/geode-sdk/DevTools/releases/download/v1.3.0/geode.devtools.geode" - + responses: - '204': - description: OK - '400': - description: Invalid download URL / the mod already exists + "204": + description: No Content (Mod created) + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServerError" + + /mods/{id}: + get: + tags: + - "mods" + summary: Get info for a mod + description: Returns info for the mod, without dependencies and incompatibilities + parameters: + - $ref: "#/components/parameters/ModID" - /mods/{id}/latest: get: tags: - mods - summary: Get info for the latest version of a mod + summary: Get info for the latest version of a mod (NOT YET IMPLEMENTED) description: Returns info for the current latest version of the mod - parameters: - - $ref: '#/components/parameters/ModID' + parameters: + - $ref: "#/components/parameters/ModID" - responses: - '200': + responses: + "200": description: OK content: - application/json: + application/json: schema: - $ref: '#/components/schemas/ModVersion' + $ref: "#/components/schemas/ModVersion" /mods/{id}/versions: - get: + post: tags: - mods - summary: Get all versions of a mod - parameters: - - $ref: '#/components/parameters/ModID' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Mod' - + summary: Create a new version of a mod + description: This endpoint is only used for adding a new version of a mod. For creating a new mod, use the POST /mods endpoint. + security: + - bearerAuth: [] + + parameters: + - $ref: "#/components/parameters/ModID" + + requestBody: + content: + application/json: + schema: + type: object + properties: + download_link: + type: string + description: The download URL for the .geode file. You can use a Github Release for this. + examples: + - "https://github.com/geode-sdk/NodeIDs/releases/download/v1.0.0/geode.node-ids.geode" + responses: + "204": + description: No Content (Mod version created) + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFoundError" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServerError" + /mods/{id}/versions/{version}: get: tags: - mods summary: Get info for a specific version of a mod - parameters: - - $ref: '#/components/parameters/ModID' - - $ref: '#/components/parameters/ModVersion' - responses: - '200': + parameters: + - $ref: "#/components/parameters/ModID" + - $ref: "#/components/parameters/ModVersion" + responses: + "200": description: OK - content: - application/json: + content: + application/json: schema: - $ref: '#/components/schemas/ModVersion' + $ref: "#/components/schemas/ModVersion" + "404": + $ref: "#/components/responses/NotFoundError" + "500": + $ref: "#/components/responses/InternalServerError" + + /mods/{id}/versions/{version}/download: + get: + tags: + - mods + summary: Download a specific version of a mod + parameters: + - $ref: "#/components/parameters/ModID" + - $ref: "#/components/parameters/ModVersion" + responses: + "302": + description: Redirect to the actual mod download link + "404": + $ref: "#/components/responses/NotFoundError" + "500": + $ref: "#/components/responses/InternalServerError" /mods/updates: post: tags: - mods - summary: Get available mod updates + summary: Get available mod updates (NOT IMPLEMENTED) description: This is only POST because i want it to have a body parameters: - name: platform in: query required: false - schema: - $ref: '#/components/schemas/Platform' - - $ref: '#/components/parameters/GeodeVersionQuery' - - requestBody: - content: - application/json: - schema: + schema: + $ref: "#/components/schemas/Platform" + - $ref: "#/components/parameters/GeodeVersionQuery" + + requestBody: + content: + application/json: + schema: type: array items: type: object properties: id: - $ref: '#/components/schemas/ModID' + $ref: "#/components/schemas/ModID" version: - $ref: '#/components/schemas/ModVersionString' + $ref: "#/components/schemas/ModVersionString" responses: - '200': + "200": description: OK content: - application/json: + application/json: schema: type: string - - /users/{id}: - get: - tags: - - user - parameters: - - name: id - in: path - required: true - schema: - type: integer - summary: Get information about a user - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/User' + + # /users/{id}: + + # get: + # tags: + # - user + # parameters: + # - name: id + # in: path + # required: true + # schema: + # type: integer + # summary: Get information about a user + # responses: + # "200": + # description: OK + # content: + # application/json: + # schema: + # $ref: "#/components/schemas/User" components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: uuid schemas: ModID: type: string - pattern: '^[\w\-]+\.[\w\-]+$' + pattern: '[a-z0-9_\-]+\.[a-z0-9_\-]+' description: Mod ID - examples: + examples: - geode.devtools - mat.circle-tool - + ModVersionString: type: string pattern: '^v?\d+\.\d+\.\d+(?:-.+)?$' - examples: + examples: - v1.0.0 - v2.3.4 - 1.3.0 - v1.0.0-beta - + GDVersionString: type: string examples: - 2.200 - 2.204 - 2.205 - + GDVersionObject: type: object properties: win: anyOf: - - type: 'null' + - type: "null" - $ref: "#/components/schemas/GDVersionString" mac: oneOf: - - type: 'null' + - type: "null" - $ref: "#/components/schemas/GDVersionString" ios: oneOf: - - type: 'null' + - type: "null" - $ref: "#/components/schemas/GDVersionString" - android: + android32: oneOf: - - type: 'null' + - type: "null" + - $ref: "#/components/schemas/GDVersionString" + android64: + oneOf: + - type: "null" - $ref: "#/components/schemas/GDVersionString" - UserSimple: type: object properties: @@ -234,7 +301,7 @@ components: required: - id - name - + User: type: object properties: @@ -255,23 +322,36 @@ components: Mod: type: object - properties: + properties: id: - $ref: '#/components/schemas/ModID' + $ref: "#/components/schemas/ModID" repository: oneOf: - - type: 'null' + - type: "null" - type: string examples: - "https://github.com/geode-sdk/geode" latest_version: - $ref: '#/components/schemas/ModVersionString' - validated: - type: boolean + $ref: "#/components/schemas/ModVersionString" + tags: + type: array + items: + type: string + examples: + - "enhancement" + - "gameplay" versions: type: array items: - $ref: '#/components/schemas/ModVersion' + $ref: "#/components/schemas/ModVersion" + about: + type: string + examples: + - "This mod adds bugfixes to the game" + changelog: + type: string + examples: + - "Fixed a bug with the mod" required: - id - latest_version @@ -285,6 +365,8 @@ components: type: string examples: - Devtools + validated: + type: boolean description: type: string early_load: @@ -292,9 +374,9 @@ components: api: type: boolean geode: - $ref: '#/components/schemas/ModVersionString' + $ref: "#/components/schemas/ModVersionString" version: - $ref: '#/components/schemas/ModVersionString' + $ref: "#/components/schemas/ModVersionString" download_link: type: string examples: @@ -311,33 +393,32 @@ components: - $ref: "#/components/schemas/GDVersionString" - $ref: "#/components/schemas/GDVersionObject" mod_id: - $ref: '#/components/schemas/ModID' - + $ref: "#/components/schemas/ModID" + Platform: type: string - enum: + enum: - win - mac - android32 - android64 - ios - - parameters: + parameters: ModID: name: id description: Mod ID in: path required: true schema: - $ref: '#/components/schemas/ModID' - + $ref: "#/components/schemas/ModID" + ModVersion: name: version description: Mod Version in: path required: true schema: - $ref: '#/components/schemas/ModVersionString' + $ref: "#/components/schemas/ModVersionString" GeodeVersionQuery: name: geode @@ -345,8 +426,8 @@ components: description: Geode version being used required: false schema: - $ref: '#/components/schemas/ModVersionString' - + $ref: "#/components/schemas/ModVersionString" + Page: name: page in: query @@ -355,12 +436,69 @@ components: example: 1 schema: type: integer - + PerPage: - name: per_page + name: per_page in: query description: Number of elements to fetch per page required: false example: 10 schema: type: integer + responses: + Unauthorized: + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + error: + type: string + example: "You are not authorized to access this resource" + payload: + type: "null" + BadRequest: + description: Bad request + content: + application/json: + schema: + type: object + properties: + error: + type: string + payload: + type: "null" + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + type: object + properties: + error: + type: string + payload: + type: "null" + ForbiddenError: + description: Forbidden + content: + application/json: + schema: + type: object + properties: + error: + type: string + payload: + type: "null" + NotFoundError: + description: Not Found + content: + application/json: + schema: + type: object + properties: + error: + type: string + payload: + type: "null"