document new study PGN import endpoint - for lichess-org/lila#13454

doc/specs/lichess-api.yaml

@@ -3743,6 +3743,78 @@ paths:
                 type: string
                 example: 'Tue, 25 Apr 2023 13:23:09 GMT'
 
+  /api/study/{studyId}/import-pgn:
+    post:
+      operationId: apiStudyImportPGN
+      summary: Import PGN into a study
+      description: |
+        Imports arbitrary PGN into an existing [study](https://lichess.org/study). Creates a new chapter in the study.
+
+        If the PGN contains multiple games (separated by 2 or more newlines)
+        then multiple chapters will be created within the study.
+
+        Note that a study can contain at most 64 chapters.
+      tags:
+        - Studies
+      security:
+        - OAuth2: ["study:write"]
+      parameters:
+        - in: path
+          name: studyId
+          description: ID of the study
+          schema:
+            type: string
+          required: true
+      requestBody:
+        description: Parameters of the import
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: |
+                    Name of the new chapter.
+                    If multiple chapters are created, the names will be infered from the PGN tags.
+                  minLength: 1
+                  maxLength: 100
+                pgn:
+                  type: string
+                  description: |
+                    PGN to import. Can contain multiple games separated by 2 or more newlines.
+                orientation:
+                  type: string
+                  description: Default board orientation.
+                  enum:
+                    - white
+                    - black
+                  default: white
+                variant:
+                  $ref: '#/components/schemas/VariantKey'
+              required:
+                - name
+                - pgn
+      responses:
+        "200":
+          description: The chapters that were created.
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+                default: "'*'"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StudyImportPgnChapters'
+        "400":
+          description: The creation of the Swiss tournament failed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
   /study/by/{username}/export.pgn:
     get:
       operationId: studyExportAllPgn
@@ -8567,6 +8639,14 @@ components:
         "updatedAt": 1469965025205
       }
 
+    StudyImportPgnChapters:
+      example: {
+        "chapters": [{
+          "id": "WTvnkWAL",
+          "name": "Game 2"
+        }],
+      }
+
     Title:
       type: string
       enum: [GM, WGM, IM, WIM, FM, WFM, NM, CM, WCM, WNM, LM, BOT]