12 files changed, 96 insertions, 23 deletions
diff --git a/app/assets/javascripts/environments/components/environment_monitoring.vue b/app/assets/javascripts/environments/components/environment_monitoring.vue
index 612edd8855d..4dc2c0ec1bd 100644
--- a/app/assets/javascripts/environments/components/environment_monitoring.vue
+++ b/app/assets/javascripts/environments/components/environment_monitoring.vue
@@ -1,13 +1,12 @@
 <script>
-import { GlDeprecatedButton, GlTooltipDirective, GlIcon } from '@gitlab/ui';
+import { GlButton, GlTooltipDirective } from '@gitlab/ui';
 import { __ } from '~/locale';
 /**
  * Renders the Monitoring (Metrics) link in environments table.
  */
 export default {
   components: {
-    GlIcon,
-    GlDeprecatedButton,
+    GlButton,
   },
   directives: {
     GlTooltip: GlTooltipDirective,
@@ -26,15 +25,14 @@ export default {
 };
 </script>
 <template>
-  <gl-deprecated-button
+  <gl-button
     v-gl-tooltip
     :href="monitoringUrl"
     :title="title"
     :aria-label="title"
-    class="monitoring-url d-none d-sm-none d-md-block"
+    class="monitoring-url gl-display-none gl-display-sm-none gl-display-md-block"
+    icon="chart"
     rel="noopener noreferrer nofollow"
     variant="default"
-  >
-    <gl-icon name="chart" />
-  </gl-deprecated-button>
+  />
 </template>
diff --git a/changelogs/unreleased/migration-monitoring-btn.yml b/changelogs/unreleased/migration-monitoring-btn.yml
new file mode 100644
index 00000000000..22d6fda23ff
--- /dev/null
+++ b/changelogs/unreleased/migration-monitoring-btn.yml
@@ -0,0 +1,5 @@
+---
+title: Migrating to gl-button in Environments table
+merge_request: 40444
+author:
+type: changed
diff --git a/changelogs/unreleased/winniehell-openapi-mvc.yml b/changelogs/unreleased/winniehell-openapi-mvc.yml
new file mode 100644
index 00000000000..5b55ebf0284
--- /dev/null
+++ b/changelogs/unreleased/winniehell-openapi-mvc.yml
@@ -0,0 +1,5 @@
+---
+title: Add first OpenAPI specification file
+merge_request: 35868
+author: winniehell
+type: other
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index b8172322c10..0d7ccb344bb 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -603,9 +603,9 @@ or `gitlab-ctl promote-to-primary-node`, either:
   bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was
   fixed.
 
-If the above does not work, another possible reason is that you have paused replication
-from the original primary node before attempting to promote this node.
+### Message: ActiveRecord::RecordInvalid: Validation failed: Enabled Geo primary node cannot be disabled
 
+This error may occur if you have paused replication from the original primary node before attempting to promote this node.
 To double check this, you can do the following:
 
 - Get the current secondary node's ID using:
diff --git a/doc/api/README.md b/doc/api/README.md
index 82cce57f47b..66d7076a125 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -4,6 +4,8 @@ Automate GitLab via a simple and powerful API.
 
 The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts.
 
+There is also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), which allows you to test the API directly from the GitLab user interface. Contributions are welcome.
+
 ## Available API resources
 
 For a list of the available resources and their endpoints, see
diff --git a/doc/api/openapi/openapi.yaml b/doc/api/openapi/openapi.yaml
new file mode 100644
index 00000000000..8aa4de62501
--- /dev/null
+++ b/doc/api/openapi/openapi.yaml
@@ -0,0 +1,26 @@
+openapi: "3.0.0"
+info:
+  description: |
+    An OpenAPI definition for the GitLab REST API.
+    Only one API resource/endpoint is currently included.
+    The intent is to expand this to match the entire Markdown documentation of the API:
+    <https://docs.gitlab.com/ee/api/>. Contributions are welcome.
+
+    When viewing this on gitlab.com, you can test API calls directly from the browser
+    against the `gitlab.com` instance, if you are logged in.
+    The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/README.html#session-cookie),
+    so each request is made using your account. 
+
+    Read more at <https://docs.gitlab.com/ee/development/documentation/styleguide.html#restful-api>.
+  version: "v4"
+  title: "GitLab API"
+  termsOfService: "https://about.gitlab.com/terms/"
+  license:
+    name: "CC BY-SA 4.0"
+    url: "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE"
+servers:
+  - url: "https://gitlab.com/api/"
+
+paths:
+  /v4/version:
+    $ref: "v4/version.yaml"
diff --git a/doc/api/openapi/v4/version.yaml b/doc/api/openapi/v4/version.yaml
new file mode 100644
index 00000000000..3a689840f4c
--- /dev/null
+++ b/doc/api/openapi/v4/version.yaml
@@ -0,0 +1,28 @@
+# Markdown documentation: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/version.md
+
+get:
+  tags:
+    - version
+  summary: "Retrieve version information for this GitLab instance."
+  operationId: "getVersion"
+  responses:
+    "401":
+      description: "unauthorized operation"
+    "200":
+      description: "successful operation"
+      content:
+        "application/json":
+          schema:
+            title: "VersionResponse"
+            type: "object"
+            properties:
+              version:
+                type: "string"
+              revision:
+                type: "string"
+          examples:
+            Example:
+              value:
+                version: "13.3.0-pre"
+                revision: "f2b05afebb0"
+
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 06b05f49b12..d87f3ceac30 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -13,10 +13,12 @@ Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/
 
 ## Documentation
 
-API endpoints must come with [documentation](documentation/styleguide.md#restful-api), unless it is internal or behind a feature flag.
+Each new or updated API endpoint must come with documentation, unless it is internal or behind a feature flag.
 The docs should be in the same merge request, or, if strictly necessary,
 in a follow-up with the same milestone as the original merge request.
 
+See the [Documentation Style Guide RESTful API section](documentation/styleguide.md#restful-api) for details on documenting API resources in Markdown as well as in OpenAPI definition files.
+
 ## Methods and parameters description
 
 Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods)
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index bfeb417fb44..4c77d95c89f 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -1738,8 +1738,13 @@ For guidance on developing GitLab with feature flags, see
 
 ## RESTful API
 
-Here is a list of must-have items for RESTful API documentation. Use them in the
-exact order that appears on this document. Further explanation is given below.
+REST API resources are documented in Markdown under [`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each resource has its own Markdown file, which is linked from `api_resources.md`.
+
+When modifying the Markdown, also update the corresponding [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) if one exists for the resource.
+If not, consider creating one. Match the latest [OpenAPI 3.0.x specification](https://swagger.io/specification/).
+(For more information, see the discussion in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).)
+
+In the Markdown doc for a resource (AKA endpoint):
 
 - Every method must have the REST API request. For example:
 
diff --git a/lib/api/internal/base.rb b/lib/api/internal/base.rb
index 17599c72243..ff687a57888 100644
--- a/lib/api/internal/base.rb
+++ b/lib/api/internal/base.rb
@@ -241,14 +241,16 @@ module API
             break { success: false, message: "Invalid token expiry date: '#{params[:expires_at]}'" }
           end
 
-          access_token = nil
+          result = ::PersonalAccessTokens::CreateService.new(
+            user, name: params[:name], scopes: params[:scopes], expires_at: expires_at
+          ).execute
 
-          ::Users::UpdateService.new(current_user, user: user).execute! do |user|
-            access_token = user.personal_access_tokens.create!(
-              name: params[:name], scopes: params[:scopes], expires_at: expires_at
-            )
+          unless result.status == :success
+            break { success: false, message: "Failed to create token: #{result.message}" }
           end
 
+          access_token = result.payload[:personal_access_token]
+
           { success: true, token: access_token.token, scopes: access_token.scopes, expires_at: access_token.expires_at }
         end
 
diff --git a/spec/frontend/environments/environment_monitoring_spec.js b/spec/frontend/environments/environment_monitoring_spec.js
index c010e271932..a73f49f1047 100644
--- a/spec/frontend/environments/environment_monitoring_spec.js
+++ b/spec/frontend/environments/environment_monitoring_spec.js
@@ -1,5 +1,5 @@
 import { shallowMount } from '@vue/test-utils';
-import { GlIcon } from '@gitlab/ui';
+import { GlButton } from '@gitlab/ui';
 import MonitoringComponent from '~/environments/components/environment_monitoring.vue';
 
 describe('Monitoring Component', () => {
@@ -15,8 +15,8 @@ describe('Monitoring Component', () => {
     });
   };
 
-  const findIcons = () => wrapper.findAll(GlIcon);
-  const findIconsByName = name => findIcons().filter(icon => icon.props('name') === name);
+  const findButtons = () => wrapper.findAll(GlButton);
+  const findButtonsByIcon = icon => findButtons().filter(button => button.props('icon') === icon);
 
   beforeEach(() => {
     createWrapper();
@@ -30,7 +30,7 @@ describe('Monitoring Component', () => {
 
   it('should render a link to environment monitoring page', () => {
     expect(wrapper.attributes('href')).toEqual(monitoringUrl);
-    expect(findIconsByName('chart').length).toBe(1);
+    expect(findButtonsByIcon('chart').length).toBe(1);
     expect(wrapper.attributes('title')).toBe('Monitoring');
     expect(wrapper.attributes('aria-label')).toBe('Monitoring');
   });
diff --git a/spec/lib/backup/repository_spec.rb b/spec/lib/backup/repository_spec.rb
index fef5e018231..c4ad239f9d7 100644
--- a/spec/lib/backup/repository_spec.rb
+++ b/spec/lib/backup/repository_spec.rb
@@ -55,7 +55,7 @@ RSpec.describe Backup::Repository do
     end
 
     [4, 10].each do |max_storage_concurrency|
-      context "max_storage_concurrency #{max_storage_concurrency}" do
+      context "max_storage_concurrency #{max_storage_concurrency}", quarantine: 'https://gitlab.com/gitlab-org/gitlab/-/issues/241701' do
         it 'creates the expected number of threads' do
           expect(Thread).to receive(:new)
             .exactly(storage_keys.length * (max_storage_concurrency + 1)).times