From cebb2e2281064daa41d67c3b718161d514424a91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20R=C3=BCegg?= Date: Thu, 9 Aug 2018 10:16:49 +0200 Subject: [PATCH] Updated REST API for project-level and global templates introduced with version 3.0.0 --- spec/swagger.yaml | 281 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 195 insertions(+), 86 deletions(-) diff --git a/spec/swagger.yaml b/spec/swagger.yaml index 9d9fbf7..85b4663 100644 --- a/spec/swagger.yaml +++ b/spec/swagger.yaml @@ -4,7 +4,7 @@ info: description: "REST API documentation for the plug-in Repository Templates for Bitbucket\ \ Server.\n The REST API allows you to maintain\ \ the project settings of the\n plug-in as\ - \ well as to assign repositories to a template." + \ well as the global repository templates." version: "v1" title: "Repository Templates for Bitbucket Server REST API" contact: @@ -16,71 +16,98 @@ info: host: "YOUR_BITBUCKET_SERVER" basePath: "/rest/templates4stash/1.0" tags: +- name: "Global templates" - name: "Project settings" -- name: "Project template mappings" +- name: "Project templates" schemes: - "http" - "https" paths: - /projects/{projectKey}/settings: + /global-templates: get: tags: - - "Project settings" - summary: "Returns the project settings of the plug-in." + - "Global templates" + summary: "Returns the defined global repository templates." description: "" - operationId: "getProjectSettings" - consumes: + operationId: "getGlobalTemplates" + produces: - "application/json" + parameters: [] + responses: + 200: + description: "Global repository templates found" + 401: + description: "The currently authenticated user does not have ADMIN credentials" + post: + tags: + - "Global templates" + summary: "Creates a global repository template." + description: "" + operationId: "createGlobalTemplate" produces: - "application/json" parameters: - - name: "projectKey" - in: "path" + - in: "body" + name: "Global template details" required: true - type: "string" + schema: + $ref: "#/definitions/GlobalTemplate" responses: 200: - description: "Project settings found" + description: "Global repository template created" + 400: + description: "Invalid input parameters like a non-existing template" 401: - description: "The currently authenticated user does not have PROJECT_ADMIN\ - \ credentials" - 404: - description: "Project not found or no project settings" + description: "The currently authenticated user does not have ADMIN credentials" put: tags: - - "Project settings" - summary: "Updates the project settings of the plug-in." + - "Global templates" + summary: "Updates a global repository template." description: "" - operationId: "updateProjectSettings" - consumes: - - "application/json" + operationId: "updateGlobalTemplate" produces: - "application/json" parameters: - - name: "projectKey" - in: "path" - required: true - type: "string" - in: "body" - name: "Project settings" + name: "Global template details" required: true schema: - $ref: "#/definitions/ProjectSettings" + $ref: "#/definitions/GlobalTemplate" responses: 200: - description: "Project settings updated" + description: "Global repository template updated" 401: - description: "The currently authenticated user does not have PROJECT_ADMIN\ - \ credentials" + description: "The currently authenticated user does not have ADMIN credentials" 404: - description: "Project not found or no project settings" - /projects/{projectKey}/template-mappings: + description: "The global template does not exist" + delete: + tags: + - "Global templates" + summary: "Deletes a global repository template." + description: "" + operationId: "deleteGlobalTemplate" + produces: + - "application/json" + parameters: + - name: "id" + in: "query" + required: false + type: "integer" + format: "int32" + responses: + 200: + description: "Global repository template deleted" + 401: + description: "The currently authenticated user does not have ADMIN credentials" + 404: + description: "The global template does not exist" + /projects/{projectKey}/project-templates: get: tags: - - "Project template mappings" - summary: "Returns the template mappings of this project." + - "Project templates" + summary: "Returns the defined project-level repository templates." description: "" - operationId: "getTemplateMappings" + operationId: "getProjectTemplates" produces: - "application/json" parameters: @@ -90,18 +117,16 @@ paths: type: "string" responses: 200: - description: "Project template mappings found" + description: "Project-level repository templates found" 401: description: "The currently authenticated user does not have PROJECT_ADMIN\ \ credentials" - 404: - description: "Project not found" post: tags: - - "Project template mappings" - summary: "Creates a template to repository mapping." + - "Project templates" + summary: "Creates a project-level repository template." description: "" - operationId: "createTemplateMapping" + operationId: "createProjectTemplate" produces: - "application/json" parameters: @@ -110,24 +135,24 @@ paths: required: true type: "string" - in: "body" - name: "Template repository mapping details" + name: "Project template details" required: true schema: - $ref: "#/definitions/TemplateMapping" + $ref: "#/definitions/ProjectTemplate" responses: 200: - description: "Template repository mapping created" + description: "Project-level repository template created" 400: - description: "Bad input parameters like a non-existing template or repositories" + description: "Invalid input parameters like a non-existing template" 401: - description: "The currently authenticated user does not have REPO_ADMIN\ + description: "The currently authenticated user does not have PROJECT_ADMIN\ \ credentials" put: tags: - - "Project template mappings" - summary: "Updates a template to repository mapping." + - "Project templates" + summary: "Updates a project-level repository template." description: "" - operationId: "updateTemplateMapping" + operationId: "updateProjectTemplate" produces: - "application/json" parameters: @@ -136,24 +161,76 @@ paths: required: true type: "string" - in: "body" - name: "Template repository mapping details" + name: "Project template details" required: true schema: - $ref: "#/definitions/TemplateMapping" + $ref: "#/definitions/ProjectTemplate" responses: 200: - description: "Template repository mapping updated" - 400: - description: "Bad input parameters like a non-existing template or repositories" + description: "Project-level repository template updated" 401: - description: "The currently authenticated user does not have REPO_ADMIN\ + description: "The currently authenticated user does not have PROJECT_ADMIN\ \ credentials" + 404: + description: "The project template does not exist" delete: tags: - - "Project template mappings" - summary: "Deletes a template repositories mapping." + - "Project templates" + summary: "Deletes a project-level repository template." description: "" - operationId: "deleteTemplateMapping" + operationId: "deleteProjectTemplate" + produces: + - "application/json" + parameters: + - name: "projectKey" + in: "path" + required: true + type: "string" + - name: "id" + in: "query" + required: false + type: "integer" + format: "int32" + responses: + 200: + description: "Project-level repository template deleted" + 401: + description: "The currently authenticated user does not have PROJECT_ADMIN\ + \ credentials" + 404: + description: "The project template does not exist" + /projects/{projectKey}/settings: + get: + tags: + - "Project settings" + summary: "Returns the project settings of the plug-in." + description: "" + operationId: "getProjectSettings" + consumes: + - "application/json" + produces: + - "application/json" + parameters: + - name: "projectKey" + in: "path" + required: true + type: "string" + responses: + 200: + description: "Project settings found" + 401: + description: "The currently authenticated user does not have PROJECT_ADMIN\ + \ credentials" + 404: + description: "Project not found or no project settings" + put: + tags: + - "Project settings" + summary: "Updates the project settings of the plug-in." + description: "" + operationId: "updateProjectSettings" + consumes: + - "application/json" produces: - "application/json" parameters: @@ -162,19 +239,38 @@ paths: required: true type: "string" - in: "body" - name: "Template repository mapping details" + name: "Project settings" required: true schema: - $ref: "#/definitions/TemplateMapping" + $ref: "#/definitions/ProjectSettings" responses: 200: - description: "Template repository mapping deleted" - 400: - description: "Bad input parameters like a non-existing template or repositories" + description: "Project settings updated" 401: - description: "The currently authenticated user does not have REPO_ADMIN\ + description: "The currently authenticated user does not have PROJECT_ADMIN\ \ credentials" + 404: + description: "Project not found or no project settings" definitions: + GlobalTemplate: + type: "object" + properties: + id: + type: "integer" + format: "int32" + description: "the ID of the global template configuration" + template: + type: "object" + description: "the template repository; just pass its repository ID, e.g.,\ + \ { \"id\": 1 }" + additionalProperties: + type: "object" + description: + type: "string" + description: "the description of the global template" + logoData: + type: "string" + description: "the base64-encoded image logo" ProjectSettings: type: "object" properties: @@ -192,11 +288,10 @@ definitions: description: "true if you want the content of a template being mirrored to\ \ a repository on its creation" default: false - defaultTemplateRepositoryId: - type: "integer" - format: "int32" - description: "the ID of the repository which should be the template for all\ - \ new repositories in this project" + forkTemplateSyncEnabled: + type: "boolean" + description: "Sync settings from template to new repository forks" + default: false settingsToUse: description: "choose all settings which should be copied (when creating a\ \ new repository with a template) or reset (when you have the periodic settings\ @@ -207,6 +302,38 @@ definitions: description: "the cron expression to use for resetting the settings of associated\ \ repositories to the one of the configured template (use null to deactivate\ \ the periodic reset)" + ProjectTemplate: + type: "object" + properties: + id: + type: "integer" + format: "int32" + description: "the ID of the project-level template configuration" + template: + type: "object" + description: "the template repository; just pass its repository ID, e.g.,\ + \ { \"id\": 1 }" + additionalProperties: + type: "object" + description: + type: "string" + description: "the description of the project-level template" + logoData: + type: "string" + description: "the base64-encoded image logo" + defaultTemplate: + type: "boolean" + description: "is default template" + default: false + repos: + type: "array" + description: "the list of repositories that should be assigned to this template;\ + \ just pass a list of repository ID's, e.g., [ { \"id\": 1 }, { \"id\":\ + \ 2 } ]. You should leave this empty for DELETE." + items: + type: "object" + additionalProperties: + type: "object" SettingsToUse: type: "object" properties: @@ -251,21 +378,3 @@ definitions: description: "(since version 2.2.0) true if the access keys of the template\ \ should be applied to associated repositories" default: false - TemplateMapping: - type: "object" - properties: - template: - type: "object" - description: "the template repository; just pass its repository ID, e.g.,\ - \ { \"id\": 1 }" - additionalProperties: - type: "object" - repos: - type: "array" - description: "the list of repositories that should be assigned to this template;\ - \ just pass a list of repository ID's, e.g., [ { \"id\": 1 }, { \"id\":\ - \ 2 } ]. You should leave this empty for DELETE." - items: - type: "object" - additionalProperties: - type: "object"