Merge branch...

Merge branch 'dmeshcharakou/add-api-maven-packages-endpoints-to-open-api-v2-documentation' into 'master'

Add API::MavenPackages endpoints to OpenApiV2 documentation

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105798



Merged-by: Aleksei Lipniagov <alipniagov@gitlab.com>
Approved-by: Raimund Hook <rhook@gitlab.com>
Approved-by: Aleksei Lipniagov <alipniagov@gitlab.com>
Co-authored-by: Dzmitry Meshcharakou <12459192-dmeshcharakou@users.noreply.gitlab.com>

config/open_api.yml

@@ -83,6 +83,8 @@ metadata:
     description: Operations related to issue links
   - name: jira_connect_subscriptions
     description: Operations related to JiraConnect subscriptions
+  - name: maven_packages
+    description: Operations related to Maven packages
   - name: merge_requests
     description: Operations related to merge requests
   - name: metadata

lib/api/api.rb

@@ -235,6 +235,7 @@ class API < ::API::Base
         mount ::API::Keys
         mount ::API::Lint
         mount ::API::Markdown
+        mount ::API::MavenPackages
         mount ::API::Members
         mount ::API::MergeRequestApprovals
         mount ::API::MergeRequests
@@ -310,7 +311,6 @@ class API < ::API::Base
       mount ::API::GroupMilestones
       mount ::API::Issues
       mount ::API::Labels
-      mount ::API::MavenPackages
       mount ::API::Notes
       mount ::API::NotificationSettings
       mount ::API::NpmInstancePackages

lib/api/maven_packages.rb

@@ -150,10 +150,17 @@ def find_and_present_package_file(package, file_name, format, params)
 
     desc 'Download the maven package file at instance level' do
       detail 'This feature was introduced in GitLab 11.6'
+      success code: 200
+      failure [
+        { code: 401, message: 'Unauthorized' },
+        { code: 403, message: 'Forbidden' },
+        { code: 404, message: 'Not Found' }
+      ]
+      tags %w[maven_packages]
     end
     params do
-      requires :path, type: String, desc: 'Package path'
-      requires :file_name, type: String, desc: 'Package file name'
+      requires :path, type: String, desc: 'Package path', documentation: { example: 'foo/bar/mypkg/1.0-SNAPSHOT' }
+      requires :file_name, type: String, desc: 'Package file name', documentation: { example: 'mypkg-1.0-SNAPSHOT.jar' }
     end
     route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
     get 'packages/maven/*path/:file_name', requirements: MAVEN_ENDPOINT_REQUIREMENTS do
@@ -190,14 +197,24 @@ def find_and_present_package_file(package, file_name, format, params)
 
     desc 'Download the maven package file at a group level' do
       detail 'This feature was introduced in GitLab 11.7'
+      success [
+        { code: 200 },
+        { code: 302 }
+      ]
+      failure [
+        { code: 401, message: 'Unauthorized' },
+        { code: 403, message: 'Forbidden' },
+        { code: 404, message: 'Not Found' }
+      ]
+      tags %w[maven_packages]
     end
     params do
-      requires :id, type: String, desc: 'The ID of a group'
+      requires :id, types: [String, Integer], desc: 'The ID or URL-encoded path of the group'
     end
     resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
       params do
-        requires :path, type: String, desc: 'Package path'
-        requires :file_name, type: String, desc: 'Package file name'
+        requires :path, type: String, desc: 'Package path', documentation: { example: 'foo/bar/mypkg/1.0-SNAPSHOT' }
+        requires :file_name, type: String, desc: 'Package file name', documentation: { example: 'mypkg-1.0-SNAPSHOT.jar' }
       end
       route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
       get ':id/-/packages/maven/*path/:file_name', requirements: MAVEN_ENDPOINT_REQUIREMENTS do
@@ -225,10 +242,20 @@ def find_and_present_package_file(package, file_name, format, params)
     resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
       desc 'Download the maven package file' do
         detail 'This feature was introduced in GitLab 11.3'
+        success [
+          { code: 200 },
+          { code: 302 }
+        ]
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not Found' }
+        ]
+        tags %w[maven_packages]
       end
       params do
-        requires :path, type: String, desc: 'Package path'
-        requires :file_name, type: String, desc: 'Package file name'
+        requires :path, type: String, desc: 'Package path', documentation: { example: 'foo/bar/mypkg/1.0-SNAPSHOT' }
+        requires :file_name, type: String, desc: 'Package file name', documentation: { example: 'mypkg-1.0-SNAPSHOT.jar' }
       end
       route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
       get ':id/packages/maven/*path/:file_name', requirements: MAVEN_ENDPOINT_REQUIREMENTS do
@@ -250,10 +277,18 @@ def find_and_present_package_file(package, file_name, format, params)
 
       desc 'Workhorse authorize the maven package file upload' do
         detail 'This feature was introduced in GitLab 11.3'
+        success code: 200
+        failure [
+          { code: 400, message: 'Bad Request' },
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not Found' }
+        ]
+        tags %w[maven_packages]
       end
       params do
-        requires :path, type: String, desc: 'Package path'
-        requires :file_name, type: String, desc: 'Package file name', regexp: Gitlab::Regex.maven_file_name_regex
+        requires :path, type: String, desc: 'Package path', documentation: { example: 'foo/bar/mypkg/1.0-SNAPSHOT' }
+        requires :file_name, type: String, desc: 'Package file name', regexp: Gitlab::Regex.maven_file_name_regex, documentation: { example: 'mypkg-1.0-SNAPSHOT.pom' }
       end
       route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
       put ':id/packages/maven/*path/:file_name/authorize', requirements: MAVEN_ENDPOINT_REQUIREMENTS do
@@ -266,10 +301,19 @@ def find_and_present_package_file(package, file_name, format, params)
 
       desc 'Upload the maven package file' do
         detail 'This feature was introduced in GitLab 11.3'
+        success code: 200
+        failure [
+          { code: 400, message: 'Bad Request' },
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not Found' },
+          { code: 422, message: 'Unprocessable Entity' }
+        ]
+        tags %w[maven_packages]
       end
       params do
-        requires :path, type: String, desc: 'Package path'
-        requires :file_name, type: String, desc: 'Package file name', regexp: Gitlab::Regex.maven_file_name_regex
+        requires :path, type: String, desc: 'Package path', documentation: { example: 'foo/bar/mypkg/1.0-SNAPSHOT' }
+        requires :file_name, type: String, desc: 'Package file name', regexp: Gitlab::Regex.maven_file_name_regex, documentation: { example: 'mypkg-1.0-SNAPSHOT.pom' }
         requires :file, type: ::API::Validations::Types::WorkhorseFile, desc: 'The package file to be published (generated by Multipart middleware)', documentation: { type: 'file' }
       end
       route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true