Metadata-Version: 2.4
Name: ost-skg-if-api-tools
Version: 0.1.3
Summary: This project merges multiple OpenAPI specifications extensions into a single core specification for SKG IF.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: toml>=0.10.2
Requires-Dist: uvicorn>=0.34.2
Dynamic: license-file

# OpenAPI merge spec

Specify what should be changed in/added to the SKG-IF OpenAPI YAML, which supports the core SKG-IF data model, for an extension. RThis document will use an example __server__ extension.

## Header

Identify the extension. Potentially specify which extension(s) it extends and should already have been merged in the core OpenAPI YAML.

```yaml
extension: service
# depends-on: foo
# depends-on: bar
skg-if-api:
```

## Add tags
Add one or more tags. Each tag key, e.g. `tag-service`, should be unique. The `+` prefix tells the merger to add the tag.

```yaml
  +tag-service:
    name: Service
    description: Lorem ipsum dolor sit amet. 
  #+tag-another:
```

## Add schemas

Add one or more schemas. Each schema key, e.g. `path-service`, should be unique. The `+` prefix tells the merger to add the schema.

```yaml
  +path-service:
    '/services/{local_identifier}':
      get:
        tags:
            - Service
  ...
  +path-services:
    '/services':
      get:
        tags:
            - Service
  ...
```

### Modify a schema

Modify an existing (core) schema. Add the `~` prefix to the key of the schema to modify. Then copy all the steps that are needed to get to where a field has to be added or modified. In the example below its up to `properties`, to which `services` is added indicated by the `+` prefix. To step into the right item of a list the right position can be achieved with empty `-` items. The `~enum` showcases a modification of its value list, i.e. adding the `portal` value.

```yaml
~schema-venue:
    Venue:
      allOf:
        -
        - type: object
          properties:
            type:
              ~enum: portal
            +services:
              type: array
              items:
                $ref: '#/components/schemas/Service'
```
