@scouterna/scoutnet-openapi 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## [0.2.0](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.9...scoutnet-openapi-v0.2.0) (2025-07-23)
+
+
+### Features
+
+* add troop and section support to groups endpoint ([dddaac0](https://github.com/Scouterna/scoutnet-api/commit/dddaac0ae17632fa76dc13dafb34af06044be620))
+
+## [0.1.9](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.8...scoutnet-openapi-v0.1.9) (2025-07-23)
+
+
+### Bug Fixes
+
+* fix linter issues ([#19](https://github.com/Scouterna/scoutnet-api/issues/19)) ([9e7bfa9](https://github.com/Scouterna/scoutnet-api/commit/9e7bfa9b5e76de90babd632c3e725226d2e75088))
+
+## [0.1.8](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.7...scoutnet-openapi-v0.1.8) (2025-06-20)
+
+
+### Bug Fixes
+
+* move schema to make referencing simpler. ([a6b2708](https://github.com/Scouterna/scoutnet-api/commit/a6b27081c761261acc82df8a2978fc0a77607e8b))
+
+## [0.1.7](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.6...scoutnet-openapi-v0.1.7) (2025-06-20)
+
+
+### Bug Fixes
+
+* break out endpoints into separate files ([9f1d1b0](https://github.com/Scouterna/scoutnet-api/commit/9f1d1b076bd5a6abbed5023b51da27abeb2096fe))
+* symlink openapi document into public. ([4e11f21](https://github.com/Scouterna/scoutnet-api/commit/4e11f213eba206dd3787f03e694074b51c27cb22))
+
+## [0.1.6](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.5...scoutnet-openapi-v0.1.6) (2025-03-30)
+
+
+### Bug Fixes
+
+* include necessary files in packages ([3b71721](https://github.com/Scouterna/scoutnet-api/commit/3b7172133a6857c0fe2d78a2cee313a241aaa1c8))
+
+## [0.1.5](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.4...scoutnet-openapi-v0.1.5) (2025-03-30)
+
+
+### Bug Fixes
+
+* add metadata to packages ([e2a5728](https://github.com/Scouterna/scoutnet-api/commit/e2a5728ba5ec3604f46a4d70a9ac891b399073d9))
+
+## [0.1.4](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.3...scoutnet-openapi-v0.1.4) (2025-03-30)
+
+
+### Bug Fixes
+
+* add author to public packages ([e963310](https://github.com/Scouterna/scoutnet-api/commit/e963310c54ece98eda03ea85a2bea8dd3fb98e08))
+
+## [0.1.3](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.2...scoutnet-openapi-v0.1.3) (2025-03-27)
+
+
+### Bug Fixes
+
+* add translation to destination_list ([725952a](https://github.com/Scouterna/scoutnet-api/commit/725952a044a9c1b9769e76b36c9db192566dfce6))
+
+## [0.1.2](https://github.com/Scouterna/scoutnet-api/compare/scoutnet-openapi-v0.1.1...scoutnet-openapi-v0.1.2) (2025-03-27)
+
+
+### Bug Fixes
+
+* improve basicAuth description ([e9ecf52](https://github.com/Scouterna/scoutnet-api/commit/e9ecf526f0673a6a759a33893c066c2129b0d18b))
+* improve map descriptions ([823fcd0](https://github.com/Scouterna/scoutnet-api/commit/823fcd0b5c38bd538773f4892169f4de1d48364c))
+* rename body_key_list ([4a2607f](https://github.com/Scouterna/scoutnet-api/commit/4a2607f59faa4996d20762e79b8e6e419c69eadc))
+
+## [0.1.1](https://github.com/Scouterna/scoutnet-api/compare/@scoutnet/scoutnet-openapi-v0.1.0...@scoutnet/scoutnet-openapi-v0.1.1) (2025-03-27)
+
+
+### Bug Fixes
+
+* improve basicAuth description ([e9ecf52](https://github.com/Scouterna/scoutnet-api/commit/e9ecf526f0673a6a759a33893c066c2129b0d18b))
+* improve map descriptions ([823fcd0](https://github.com/Scouterna/scoutnet-api/commit/823fcd0b5c38bd538773f4892169f4de1d48364c))
+
+## 0.1.0 (2025-03-27)
+
+
+### Bug Fixes
+
+* improve map descriptions ([823fcd0](https://github.com/Scouterna/scoutnet-api/commit/823fcd0b5c38bd538773f4892169f4de1d48364c))

package/README.md

@@ -0,0 +1,4 @@
+# Scoutnet OpenAPI document
+
+This package contains the OpenAPI document for the Scoutnet API. The root
+document is located at `/schema/scoutnet.yaml`. 

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@scouterna/scoutnet-openapi",
+  "version": "0.2.0",
+  "description": "The OpenAPI document for the Scoutnet API, neatly packaged for NPM.",
+  "keywords": [
+    "scouterna",
+    "scoutnet"
+  ],
+  "author": "Malcolm Nihlén <malcolm.nihlen@scouterna.se>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Scouterna/scoutnet-api.git",
+    "directory": "packages/scoutnet-openapi"
+  },
+  "files": [
+    "schema",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ]
+}

package/schema/components/address.yaml

@@ -0,0 +1,28 @@
+type: object
+properties:
+  care_of:
+    type: string
+  location_name:
+    type: string
+  line_1:
+    type: string
+  line_2:
+    type: string
+  line_3:
+    type: string
+  post_code:
+    type: string
+  post_town:
+    type: string
+  latitude:
+    type: string
+  longitude:
+    type: string
+  info:
+    type: string
+  country_code:
+    type: string
+  section_name:
+    type: string
+  section_priority:
+    type: boolean

package/schema/components/body.yaml

@@ -0,0 +1,26 @@
+type: object
+properties:
+  body_key:
+    type: string
+    description: Unique key for the body. Usually body type and body ID separated by an underscore.
+  body_name:
+    type: string
+    description: The name of the body.
+  body_type:
+    type: string
+    enum:
+      - organisation
+      - region
+      - network
+      - district
+      - corps
+      - group
+      - troop
+      - patrol
+  body_id:
+    type: number
+    description: ID of the body.
+  organisation_id:
+    type: number
+    description: ID of the organisation this body belongs to. If this body is an organisation, this is the same as body_id.
+  

package/schema/components/checkin.yaml

@@ -0,0 +1,15 @@
+type: object
+properties:
+  checked_in:
+    type: number
+    enum: [0, 1]
+    description: Set to 1 to mark the participant as checked in, 0 to mark as checked out.
+  comment:
+    example: "Checked in by Scoutin checkin system"
+    type: string
+    description: A comment to be stored with the check-in. If checked_in is not provided a comment will be stored without changing the check-in state.
+  attended:
+    type: number
+    enum: [0, 1]
+    default: 1
+    description: Only applicable when checking out. Set to 1 to mark the participant as attended, 0 to mark as not attended. Default is 1.

package/schema/components/checkin_response.yaml

@@ -0,0 +1,38 @@
+type: object
+properties:
+  checked_in:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that were checked in.
+  checked_out_attended:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that were checked out and marked as attended.
+  checked_out_not_attended:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that were checked out and marked as not attended.
+  unchanged:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that were not changed. If only a comment was added, the member is still in this list.
+  not_found:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that exist but are not participants on the project.
+  no_member:
+    type: array
+    items:
+      type: number
+    description: List of member IDs that do not exist in the system.
+  total:
+    type: number
+    description: Total number of members that were processed. Unchanged members are counted as well.
+  updated_questions:
+    type: {}
+    description: NOT YET DOCUMENTED

package/schema/components/district.yaml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the district.
+  groups:
+    type: object
+    additionalProperties:
+      $ref: './group.yaml'

package/schema/components/group.yaml

@@ -0,0 +1,77 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the group.
+  description:
+    type: string
+    description: A description of the group.
+  group_no:
+    type: number
+    description: Group ID number.
+  corps_id:
+    type: number
+    description: Corps or "samverkansorganisation". `null` means Scouterna.
+  group_types:
+    type: array
+    items:
+      type: number
+    description: |
+      1: Scoutkår
+      2: Sjöscoutkår
+      3: Hub-Kår
+  troop_types:
+    type: array
+    items:
+      type: number
+    description: |
+      1: Bäverscouter
+      2: Spårarscouter
+      3: Upptäckarscouter
+      4: Äventyrarscouter
+      5: Utmanarscouter
+      6: Roverscouter
+      7: Annat
+      8: Familjescouter
+  municipality_id:
+    type: number
+    description: Municipality ID. Name can be found in the region object.
+  county_id:
+    type: number
+    description: County ID. Name can be found in the region object.
+  public_registration_enabled:
+    type: boolean
+    description: Whether the group is open for new members or not.
+  destination_list:
+    type: number
+    description: |
+      Destination list for public registration.
+      1: Medlemskap som väntar på godkännande (Membership waiting for approval)
+      2: Flytta till väntelista (Move to waiting list)
+  badges:
+    type: {}
+    description: NOT YET DOCUMENTED
+  troops:
+    type: object
+    additionalProperties:
+      $ref: './group_troop.yaml'
+  sections:
+    type: object
+    additionalProperties:
+      $ref: './group_section.yaml'
+  addresses:
+    type: object
+    additionalProperties:
+      $ref: './address.yaml'
+  email:
+    type: object
+    additionalProperties:
+      type: string
+  email_membership:
+    type: object
+    additionalProperties:
+      type: string
+  project_stats:
+    type: object
+    additionalProperties:
+      $ref: './project_stats.yaml'

package/schema/components/group_section.yaml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the troop.
+  description:
+    type: string
+    description: A description of the troop.
+  id:
+    type: number
+    description: Section ID number.
+  address_ids:
+    type: {}
+    description: NOT YET DOCUMENTED

package/schema/components/group_troop.yaml

@@ -0,0 +1,28 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the troop.
+  type:
+    type: number
+    description: |
+      1: Bäverscouter
+      2: Spårarscouter
+      3: Upptäckarscouter
+      4: Äventyrarscouter
+      5: Utmanarscouter
+      6: Roverscouter
+      7: Annat
+      8: Familjescouter
+  min_age:
+    type: number
+    description: Minimum age for the troop.
+  max_age:
+    type: number
+    description: Maximum age for the troop.
+  meeting_info:
+    type: {}
+    description: NOT YET DOCUMENTED
+  section_id:
+    type: number
+    description: ID of the section this troop belongs to.

package/schema/components/organisation.yaml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the organisation.
+  regions:
+    type: object
+    additionalProperties:
+      $ref: './region.yaml'

package/schema/components/project_get_participants_labels.yaml

@@ -0,0 +1,18 @@
+type: object
+properties:
+  member_status:
+    type: object
+    additionalProperties:
+      type: string
+  sex:
+    type: object
+    additionalProperties:
+      type: string
+  project_fee:
+    type: object
+    additionalProperties:
+      type: string
+  contact_type:
+    type: object
+    additionalProperties:
+      type: string

package/schema/components/project_member.yaml

@@ -0,0 +1,81 @@
+type: object
+properties:
+  checked_in:
+    type: [boolean, 'null']
+  attended:
+    type: [boolean, 'null']
+  cancelled:
+    type: [boolean, 'null']
+  member_status:
+    type: [number, 'null']
+  member_no:
+    type: [number, 'null']
+  group_registration:
+    type: [boolean, 'null']
+  first_name:
+    type: [string, 'null']
+  last_name:
+    type: [string, 'null']
+  ssno:
+    type: [string, 'null']
+  registration_date:
+    type: [string, 'null']
+  cancelled_date:
+    type: [string, 'null']
+  primary_email:
+    type: [string, 'null']
+  fee_id:
+    type: [number, 'null']
+  primary_membership_info:
+    type: [object, array, 'null']
+    properties:
+      patrol_id:
+        type: [number, 'null']
+      patrol_name:
+        type: [string, 'null']
+      troop_id:
+        type: [number, 'null']
+      troop_name:
+        type: [string, 'null']
+      group_id:
+        type: [number, 'null']
+      group_name:
+        type: [string, 'null']
+      district_id:
+        type: [number, 'null']
+      district_name:
+        type: [string, 'null']
+      region_id:
+        type: [number, 'null']
+      region_name:
+        type: [string, 'null']
+      organisation_id:
+        type: [number, 'null']
+      organisation_name:
+        type: [string, 'null']
+  group_registration_info:
+    type: [object, array, 'null']
+    properties:
+      group_id:
+        type: [number, 'null']
+      patrol_id:
+        type: [number, 'null']
+      group_name:
+        type: [string, 'null']
+      org_id:
+        type: [number, 'null']
+      org_name:
+        type: [string, 'null']
+      district_id:
+        type: [number, 'null']
+      district_name:
+        type: [string, 'null']
+      patrol_name:
+        type: [string, 'null']
+  questions:
+    type: {}
+    description: NOT YET DOCUMENTED
+  contact_info:
+    type: object
+    additionalProperties:
+      type: string

package/schema/components/project_stats.yaml

@@ -0,0 +1,11 @@
+type: object
+properties:
+  project_id:
+    type: number
+  group_participants:
+    type: number
+  project_name:
+    type: string
+  questions:
+    type: {}
+    description: NOT YET DOCUMENTED

package/schema/components/region.yaml

@@ -0,0 +1,22 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the region.
+  districts:
+    type: object
+    additionalProperties:
+      $ref: './district.yaml'
+  corps:
+    type: {}
+    description: NOT YET DOCUMENTED
+  municipalities:
+    type: object
+    description: Key-value map of municipality IDs (used in the response) to their names.
+    additionalProperties:
+      type: string
+  conties:
+    type: object
+    description: Key-value map of country IDs (used in the response) to their names.
+    additionalProperties:
+      type: string

package/schema/paths/body_key_list.yaml

@@ -0,0 +1,21 @@
+get:
+  summary: |
+    Restricted endpoint. Get a list of all bodies and their relations to
+    each other
+  description: |
+    For security reasons this endpoint is not publicly available and can
+    only be used by internally developed systems.
+  operationId: listBodyKeys
+  tags:
+    - global
+  responses:
+    '200':
+      description: A list of all bodies and their relations to each other.
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties:
+              $ref: ../components/body.yaml
+    '401':
+      $ref: ../responses/not_authorized.yaml

package/schema/paths/project_checkin.yaml

@@ -0,0 +1,29 @@
+put:
+  summary: Update the check-in state of participant(s) on the project
+  description: Update the check-in state of participant(s) on the project.
+  operationId: updateCheckin
+  tags:
+    - project
+  requestBody:
+    description: |
+      An object where the keys are member IDs and the values are objects
+      with check-in details.
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          propertyNames:
+            pattern: '^[0-9]+$'
+            description: A valid member ID
+          additionalProperties:
+            $ref: ../components/checkin.yaml
+  responses:
+    '200':
+      description: A summary of the check-in operation.
+      content:
+        application/json:
+          schema:
+            $ref: ../components/checkin_response.yaml
+    '401':
+      $ref: ../responses/not_authorized.yaml

package/schema/paths/project_get_groups.yaml

@@ -0,0 +1,18 @@
+get:
+  summary: Get a list of groups with members attending a project
+  description: Get a list of groups with members attending a project
+  operationId: getProjectGroups
+  tags:
+    - project
+  responses:
+    '200':
+      description: |
+        Keys of the response object are group IDs and values are group objects.
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties:
+              $ref: ../components/organisation.yaml
+    '401':
+      $ref: ../responses/not_authorized.yaml

package/schema/paths/project_get_participants.yaml

@@ -0,0 +1,25 @@
+get:
+  summary: Get a list of members who are registered on the project
+  description: Get a list of members who are registered on the project
+  operationId: getProjectParticipants
+  tags:
+    - project
+  responses:
+    '200':
+      description: A list of members registered on the project.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              participants:
+                type:
+                  - object
+                  - array
+                  - 'null'
+                additionalProperties:
+                  $ref: ../components/project_member.yaml
+              labels:
+                $ref: ../components/project_get_participants_labels.yaml
+    '401':
+      $ref: ../responses/not_authorized.yaml

package/schema/responses/not_authorized.yaml

@@ -0,0 +1 @@
+description: When unauthorized there will be no response body.

package/schema/scoutnet.yaml

@@ -0,0 +1,46 @@
+openapi: 3.1.0
+info:
+  title: Scoutnet API
+  summary: >-
+    Scoutnet is the member management system for the Guides and Scouts of
+    Sweden.
+  description: |
+    Scoutnet is the member management system for the Guides and Scouts of
+    Sweden. This API provides access to various resources related to projects,
+    groups, and participants.
+  version: 0.2.0
+  license:
+    name: MIT
+    identifier: MIT
+  contact:
+    name: Scoutnet
+    url: https://github.com/Scouterna/scoutnet-api
+tags:
+  - name: project
+    description: Endpoints related to "arrangemang"
+  - name: global
+    description: Endpoints that do not belong to a specific type of resource
+servers:
+  - url: https://s1.test.custard.no/api
+    description: Test server
+  - url: https://scoutnet.se/api
+    description: Production server
+components:
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+      description: |
+        Use the ID of the resource you're accessing as username and the
+        corresponding API key as password.
+security:
+  - basicAuth: []
+paths:
+  /body_key_list:
+    $ref: ./paths/body_key_list.yaml
+  /project/get/groups:
+    $ref: ./paths/project_get_groups.yaml
+  /project/get/participants:
+    $ref: ./paths/project_get_participants.yaml
+  /project/checkin:
+    $ref: ./paths/project_checkin.yaml