Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial commit for OEM and Redfish OpenAPI consolidator. #325

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
components:
schemas:
ComputerSystem_v1_12_0_ComputerSystem:
properties:
Oem:
additionalProperties: true
description: Contoso's OEM extension.
properties:
MyFoo :
type : string
type: object
x-longDescription: Some long description.
x-patternProperties:
^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message)\.[a-zA-Z_][a-zA-Z0-9_]*$:
description: This property shall specify a valid Contoso property.
^[A-Za-z0-9_]+$:
ComputerSystem_v1_12_0_OemActions:
additionalProperties: true
description: Contoso's Action OEM extension.
properties:
MyActionParameter:
type : string

Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@

# This file contains base definitions for Contoso.

components:
schema:
blah:
type: string
blah-blah:
type: number
blah-blah-blah:
type: string

Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@

components:
schemas:
ManagerAccount_v1_6_1_ManagerAccount:
properties:
Oem:
additionalProperties: true
description: Contoso's OEM extension.
properties:
MyMAccount :
type : string

10 changes: 10 additions & 0 deletions openapi-oem-consolidator/Example/oem-contoso/Resource-OEM.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@

components:
schemas:
Resource_Oem:
additionalProperties: true
description: Contoso's OEM Base Resource extension.
properties:
A :
type : string

46 changes: 46 additions & 0 deletions openapi-oem-consolidator/Example/oem-contoso/openapi.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
## Contoso's Open API Yaml

info:
contact:
name: Contoso, Inc.
url: https://www.contoso.org
description: This contains the definition of a Redfish service with Contoso's OEM extensions.
title: Redfish
version: 'Contoso-2020.3-1.0.0'
x-copyright: Copyright 2020 DMTF and Contoso. For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright. For the full Contoso's copyright, visit https://www.contoso.org

openapi: 3.0.1

paths:
/redfish/v1/Contoso/blah:
get:
responses:
'200':
content:
application/json:
schema:
$ref: http://www.contoso.org/schemas/v1/ServiceRoot.v1_9_0.yaml#/components/schemas/ServiceRoot_v1_9_0_ServiceRoot
description: The response contains a representation of the ServiceRoot resource
default:
content:
application/json:
schema:
$ref: '#/components/schemas/RedfishError'
description: Bad/Error condition
/redfish/v1/Contoso/blahblah:
get:
responses:
'200':
content:
application/json:
schema:
$ref: http://www.contoso.org/schemas/v1/ServiceRoot.v1_9_0.yaml#/components/schemas/ServiceRoot_v1_9_0_ServiceRoot
description: The response contains a representation of the ServiceRoot resource
default:
content:
application/json:
schema:
$ref: '#/components/schemas/RedfishError'
description: Bad/Error condition


57 changes: 57 additions & 0 deletions openapi-oem-consolidator/LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
The Distributed Management Task Force (DMTF) grants rights under copyright in
this software on the terms of the BSD 3-Clause License as set forth below; no
other rights are granted by DMTF. This software might be subject to other rights
(such as patent rights) of other parties.


### Copyrights.

Copyright (c) 2020, Contributing Member(s) of Distributed Management Task Force,
Inc.. All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
* Neither the name of the Distributed Management Task Force (DMTF) nor the names
of its contributors may be used to endorse or promote products derived from this
software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


### Patents.

This software may be subject to third party patent rights, including provisional
patent rights ("patent rights"). DMTF makes no representations to users of the
standard as to the existence of such rights, and is not responsible to
recognize, disclose, or identify any or all such third party patent right,
owners or claimants, nor for any incomplete or inaccurate identification or
disclosure of such rights, owners or claimants. DMTF shall have no liability to
any party, in any manner or circumstance, under any legal theory whatsoever, for
failure to recognize, disclose, or identify any such third party patent rights,
or for such party's reliance on the software or incorporation thereof in its
product, protocols or testing procedures. DMTF shall have no liability to any
party using such software, whether such use is foreseeable or not, nor to any
patent owner or claimant, and shall have no liability or responsibility for
costs or losses incurred if software is withdrawn or modified after publication,
and shall be indemnified and held harmless by any party using the software from
any and all claims of infringement by a patent owner for such use.

DMTF Members that contributed to this software source code might have made
patent licensing commitments in connection with their participation in the DMTF.
For details, see http://dmtf.org/sites/default/files/patent-10-18-01.pdf and
http://www.dmtf.org/about/policies/disclosures.
159 changes: 159 additions & 0 deletions openapi-oem-consolidator/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
# OpenAPI OEM and Redfish Bundle Consolidator

Copyright 2020 DMTF. All rights reserved.

## About

The OpenAPI OEM and Redfish Bundle Consolidator is a tool that consolidates
a published Redfish schema bundle with an OEM's bundle into a single bundle to
compliant with OpenAPI specification.

## Requirements

This tool can run on any operating systems that has Python3 installed. The tool requires the following packages to be installed already:

* PyYaml
* ArgParse
* Pprint
* re
* glob
* os
* sys

## Usage

Consult the help provided by the tool itself for exact usage syntax:

```
usage: openapi-oem-consolidator.py --help
```

### Preparation

Before running the tool, create two directories:

* Redfish Directory
* OEM Directory

These two directories must be different and not a child directory of each other. The directory names are of your choosing.

The Redfish directory must contain the extracted DSP8010 bundle. The OEM directory will contain the OEM's files as described in [OEM Bundle Methodology](#oem-bundle-methodology)

## OEM Bundle Methodology

The OEM directory is a directory that contains two types of files:

* Normal OEM files
* Special OEM files

Special OEM files are identified by a file naming convention. Normal OEM files are any files not starting with a period and not having the special file naming convention defined in this document.

Normal OEM files are simply copied to the consolidated (i.e., output) directory. They are expected to be OpenAPI compliant especially if they are referenced by other other OpenAPI files.

There is no limitation to the number of files in this directory.

For an example of an OEM Bundle, look at the contents of the `Example` directory. These examples are not Redfish compliant. The example was tested against 2020.3 Redfish schema bundle.

### Special OEM Files

Special OEM files are files that describe to the tool how to modify the Redfish equivalent files to inject or replace OEM sections in standard Redfish schema. These files are populated by the OEM in an OEM directory.

The following subsections describe their respective special OEM file.

Lastly, all files in the Redfish directory and OEM directories are never modified. The specified output directory will contained the modified versions.

#### openapi.yaml

This file has the same filename as the Redfish one. The tool expects the OEM version to contain the following yaml sections:

* `info`
* `opeanapi`

The tool will error if the OEM's `openapi.yaml` contains a `components` section.

The tool takes the `info` section from the OEM's and replaces the `info` section in the Redfish's `openapi.yaml`.

The tool expects that the `openapi` section specify the same version as the Redfish one. If not, it is an error.

The OEM `openapi.yaml` may contain a `paths` section. The tool just merges the `path` section from both files into one.

This file is required.

#### $(ResourceName)-OEM.yaml

`$(ResourceName)` is a name of a resource such as *ManagerAccount*, *ComputerSystem*. The tool matches `$(ResourceName)-OEM.yaml` to the equivalent unversioned Redfish resource of the name `$(ResourceName).yaml`.

To replace one or more OEM sections in an unversioned Redfish resource YAML file, create a file whose name is `$(ResourceName)-OEM.yaml` in the given OEM directory.

`$(ResourceName)-OEM.yaml` must have the same YAML path as in the Redfish `$(ResourceName).yaml`.

Only OEM YAML paths are allowed in `$(ResourceName)-OEM.yaml`. All other paths will cause an error. See [OEM YAML Paths](#oem-yaml-paths) for details. The OEM YAML paths will replace the same path in the Redfish `$(ResourceName).yaml`. If a path in `$(ResourceName)-OEM.yaml` is not found in the Redfish equivalent, an error will occur.

#### $(ResourceName)-OEM.v$(ver).yaml

`$(ResourceName)` is a name of a resource such as *ManagerAccount*, *ComputerSystem*. `$(ver)` is the version, using underscore (_) as the version separator, such as *1_0_0*, *1_7_5*. The tool matches `$(ResourceName)-OEM.v$(ver).yaml` to the equivalent versioned Redfish resource of the name `$(ResourceName).v$(ver).yaml`.

To replace one or more OEM sections in a versioned Redfish resource YAML file, create a file whose name is `$(ResourceName)-OEM.v$(ver).yaml` in the given OEM directory.

`$(ResourceName)-OEM.v($ver).yaml` must have the same YAML path as in the Redfish `$(ResourceName).v$(ver).yaml`.

Only OEM YAML paths are allowed in `$(ResourceName)-OEM.v($ver)yaml`. All other paths will cause an error. See [OEM YAML Paths](#oem-yaml-paths) for details. The OEM YAML paths will replace the same path in the Redfish `$(ResourceName).v$(ver).yaml`. If a path in `$(ResourceName)-OEM.v($ver).yaml` is not found in the Redfish equivalent, an error will occur.

#### $(ResourceName)-OEM.all-vers.y

`$(ResourceName)` is a name of a resource such as *ManagerAccount*, *ComputerSystem*. The tool matches `$(ResourceName)-OEM.all-vers.yaml` to **all** versioned Redfish resource of the name `$(ResourceName).v*.yaml` where the asterisks (*) serves as a wildcard.

This method allows a single OEM file to replace all OEM sections in **all** versions of the same resource.

To replace one or more OEM sections in all versions of a versioned Redfish resource YAML file, create a file whose name is `$(ResourceName)-OEM.all-vers.yaml` in the given OEM directory.

`$(ResourceName)-OEM.all-vers.yaml` must have the same YAML path as in **one** of the versions of a versions Redfish resource of the name `$(ResourceName).v$(ver).yaml`. The tool assumes the same path, ignoring the version information embedded in YAML property names, exist in all versions. If one version does not have the same path, an error will occur.

Only OEM YAML paths are allowed in `$(ResourceName)-OEM.all-vers.yaml`. All other paths will cause an error. See [OEM YAML Paths](#oem-yaml-paths) for details. The OEM YAML paths will replace the same path in each version of the versioned Redfish `$(ResourceName).v$(ver).yaml`. If a path in `$(ResourceName)-OEM.v($ver).yaml` is not found in the Redfish equivalent, an error will occur.

### OEM YAML Paths

YAML paths are YAML object hierarchy paths. OEM YAML paths are YAML paths starting at the root/top to the first occurrence of a property/key name that meets one of these conditions:

* Property/Key name is exactly "OEM"
* Property/Key name is exactly "Oem"
* Property/Key name is exactly "Resource_Oem"
* Property/Key name ends with "OemActions"

Here are examples of OEM YAML Paths:

OEM YAML Path Example 1:

```yaml
components:
schemas:
ComputerSystem_v1_12_0_OemActions:
```

OEM YAML Path Example 2:

```yaml
components:
schemas:
ManagerAccount_v1_6_1_ManagerAccount:
properties:
Oem:

```

OEM YAML Path Example 3:

```yaml
components:
schemas:
Resource_Oem:

```

All content under an OEM YAML path will replace the equivalent path in the equivalent Redfish resource.

## Miscellaneous

The tool strips comments in YAML files when consolidating YAML files with OEM extensions. If a Redfish resource YAML file gets combined with OEM extensions, the resulting consolidated file will not contain any comments. The contents of Normal OEM files or non-consolidated Redfish YAML files are preserved as they are simply copied to output directory.

For Special OEM files, if the equivalent file in the Redfish bundle is not found, an error will result.
Loading