Merge branch 'jimcser-openapi-access-requests2' into 'master'

Documentation: Adds access request endpoint for OpenAPI spec (redo)

See merge request gitlab-org/gitlab!51000

changelogs/unreleased/add_access_request_endpoint.yml

+---
+title: Add access request endpoint to OpenAPI standard
+merge_request: 51000
+author: Jim Cser
+type: changed

doc/api/openapi/openapi.yaml

-openapi: "3.0.0"
+openapi: 3.0.0
+tags:
+  - name: version
+    description: Version
+  - name: access_requests
+    description: Access requests for projects and groups
 info:
   description: |
     An OpenAPI definition for the GitLab REST API.
-    Only one API resource/endpoint is currently included.
+    Few API resources or endpoints are 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.
 
@@ -12,15 +17,46 @@ info:
     so each request is made using your account.
 
     Read more at <https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html>.
-  version: "v4"
-  title: "GitLab API"
-  termsOfService: "https://about.gitlab.com/terms/"
+  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"
+    name: CC BY-SA 4.0
+    url: 'https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE'
 servers:
-  - url: "https://gitlab.com/api/"
+  - url: 'https://gitlab.com/api/'
+security:
+  - ApiKeyAuth: []
+
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: Private-Token
 
 paths:
+  # VERSION
   /v4/version:
-    $ref: "v4/version.yaml"
+    $ref: 'v4/version.yaml'
+
+  # ACCESS REQUESTS (PROJECTS)
+  /v4/projects/{id}/access_requests:
+    $ref: 'v4/access_requests.yaml#/accessRequestsProjects'
+
+  /v4/projects/{id}/access_requests/{user_id}/approve:
+    $ref: 'v4/access_requests.yaml#/accessRequestsProjectsApprove'
+  
+  /v4/projects/{id}/access_requests/{user_id}:
+    $ref: 'v4/access_requests.yaml#/accessRequestsProjectsDeny'
+
+  # ACCESS REQUESTS (GROUPS)
+  /v4/groups/{id}/access_requests:
+    $ref: 'v4/access_requests.yaml#/accessRequestsGroups'
+
+  /v4/groups/{id}/access_requests/{user_id}/approve:
+    $ref: 'v4/access_requests.yaml#/accessRequestsGroupsApprove'
+  
+  /v4/groupss/{id}/access_requests/{user_id}:
+    $ref: 'v4/access_requests.yaml#/accessRequestsGroupsDeny'
+

doc/api/openapi/v4/access_requests.yaml

+# Markdown documentation: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/access_requests.md
+
+#/v4/projects/{id}/access_requests
+accessRequestsProjects:
+  get:
+    description: Lists access requests for a project
+    summary: List access requests for a project
+    operationId: accessRequestsProjects_get
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the project owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+    responses:
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: ProjectAccessResponse
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                requested_at:
+                  type: string
+            example:
+              - "id": 1
+                "username": "raymond_smith"
+                "name": "Raymond Smith"
+                "state": "active"
+                "created_at": "2012-10-22T14:13:35Z"
+                "requested_at": "2012-10-22T14:13:35Z"                         
+              - "id": 2
+                "username": "john_doe"
+                "name": "John Doe"
+                "state": "active"
+                "created_at": "2012-10-22T14:13:35Z"
+                "requested_at": "2012-10-22T14:13:35Z"                         
+  post:
+    description: Requests access for the authenticated user to a project
+    summary: Requests access for the authenticated user to a project
+    operationId: accessRequestsProjects_post
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the project owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+    responses:
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: ProjectAccessRequest
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                requested_at:
+                  type: string
+            example:
+              "id": 1
+              "username": "raymond_smith"
+              "name": "Raymond Smith"
+              "state": "active"
+              "created_at": "2012-10-22T14:13:35Z"
+              "requested_at": "2012-10-22T14:13:35Z"     
+
+#/v4/projects/{id}/access_requests/{user_id}/approve
+accessRequestsProjectsApprove:
+  put:
+    description: Approves access for the authenticated user to a project
+    summary: Approves access for the authenticated user to a project
+    operationId: accessRequestsProjectsApprove_put
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the project owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+      - name: user_id
+        in: path
+        description: The userID of the access requester
+        required: true
+        schema:
+          type: integer
+      - name: access_level
+        in: query
+        description: A valid project access level.  0 = no access , 10 = guest, 20 = reporter, 30 = developer, 40 = Maintainer.  Default is 30.'
+        required: false
+        schema:
+          enum: [0, 10, 20, 30, 40]
+          default: 30
+          type: integer
+    responses:      
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: ProjectAccessApprove
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                access_level:
+                  type: integer
+            example:
+              "id": 1
+              "username": "raymond_smith"
+              "name": "Raymond Smith"
+              "state": "active"
+              "created_at": "2012-10-22T14:13:35Z"
+              "access_level": 20
+
+#/v4/projects/{id}/access_requests/{user_id}
+accessRequestsProjectsDeny:
+  delete:
+    description: Denies a project access request for the given user
+    summary: Denies a project access request for the given user
+    operationId: accessRequestProjectsDeny_delete
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the project owned by the authenticated user.
+        required: true
+        schema:
+            oneOf:
+            - type: integer
+            - type: string
+      - name: user_id
+        in: path
+        description: The user ID of the access requester
+        required: true
+        schema:
+          type: integer
+    responses:    # Does anything go here?  Markdown doc does not list a response.
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+
+#/v4/groups/{id}/access_requests
+accessRequestsGroups:
+  get:
+    description: List access requests for a group
+    summary: List access requests for a group
+    operationId: accessRequestsGroups_get
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the group owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+    responses:
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: GroupAccessResponse
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                requested_at:
+                  type: string
+            example:
+              - "id": 1
+                "username": "raymond_smith"
+                "name": "Raymond Smith"
+                "state": "active"
+                "created_at": "2012-10-22T14:13:35Z"
+                "requested_at": "2012-10-22T14:13:35Z"                         
+              - "id": 2
+                "username": "john_doe"
+                "name": "John Doe"
+                "state": "active"
+                "created_at": "2012-10-22T14:13:35Z"
+                "requested_at": "2012-10-22T14:13:35Z"   
+  post:
+    description: Requests access for the authenticated user to a group
+    summary: Requests access for the authenticated user to a group
+    operationId: accessRequestsGroups_post
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the group owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+    responses:
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: GroupAccessRequest
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                requested_at:
+                  type: string
+            example:
+              "id": 1
+              "username": "raymond_smith"
+              "name": "Raymond Smith"
+              "state": "active"
+              "created_at": "2012-10-22T14:13:35Z"
+              "requested_at": "2012-10-22T14:13:35Z"                         
+
+#/v4/groups/{id}/access_requests/{user_id}/approve
+accessRequestsGroupsApprove:
+  put:
+    description: Approves access for the authenticated user to a group
+    summary: Approves access for the authenticated user to a group
+    operationId: accessRequestsGroupsApprove_put
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the group owned by the authenticated user.
+        required: true
+        schema:
+          oneOf:
+            - type: integer
+            - type: string
+      - name: user_id
+        in: path
+        description: The userID of the access requester
+        required: true
+        schema:
+          type: integer
+      - name: access_level
+        in: query
+        description: A valid group access level.  0 = no access , 10 = Guest, 20 = Reporter, 30 = Developer, 40 = Maintainer, 50 = Owner.  Default is 30.
+        required: false
+        schema:
+          enum: [0, 10, 20, 30, 40, 50]
+          default: 30
+          type: integer
+    responses:      
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation
+        content:
+          application/json:
+            schema:
+              title: GroupAccessApprove
+              type: object
+              properties:
+                id:
+                  type: integer
+                usename:
+                  type: string
+                name:
+                  type: string
+                state:
+                  type: string
+                created_at:
+                  type: string
+                access_level:
+                  type: integer
+            example:
+              "id": 1
+              "username": "raymond_smith"
+              "name": "Raymond Smith"
+              "state": "active"
+              "created_at": "2012-10-22T14:13:35Z"
+              "access_level": 20   
+
+#/v4/groups/{id}/access_requests/{user_id}
+accessRequestsGroupsDeny:
+  delete:
+    description: Denies a group access request for the given user
+    summary: Denies a group access request for the given user
+    operationId: accessRequestsGroupsDeny_delete
+    tags:
+      - access_requests
+    parameters:
+      - name: id
+        in: path
+        description: The ID or URL-encoded path of the group owned by the authenticated user.
+        required: true
+        schema:
+            oneOf:
+            - type: integer
+            - type: string
+      - name: user_id
+        in: path
+        description: The userID of the access requester
+        required: true
+        schema:
+          type: integer
+    responses:    # Does anything go here?  Markdown doc does not list a response.
+      '401':
+        description: Unauthorized operation
+      '200':
+        description: Successful operation