NFV SpecFest Wiki

Contribute an OAS spec at ETSI Forge!

Welcome to the Wiki page for the NFV SpecFest event.

Today we offer you the opportunity to participate in the first collaborative OpenAPI specification on the ETSI Forge.

We will focus our attention on ETSI NFV GS SOL 002. Each participant to the SpecFest will create a bit of machine readable description of the textual spec and, as a result, the entire group specification will be described in the OpenAPI description language.

What you will need:

• A laptop (any operating system supported)
• A copy (paper or PDF) of NFV SOL 002 specification
• This wiki page.

Let's get started!

Set up

1. Log in at ETSI Forge inserting your EOL acconts
2. If you do not have an account yet, simply register here

Optional: Install an Editor application (VS Code)

1. Navigate to VS Code homepage and download it for your platform
2. Install the Swagger Viewer Plugin

Optional: Set up Git

To install and configure Git on your machine please refer to Get started.

Starter Kit

To help you starting up the activity we provided:

• A dedicated repository at the Forge, with the folder structure, a template of specification and some examples. Click here to visit the repository.
• A live spreadsheet to keep track of "who is doing what"

In the repository interface, click Snapshot in the menu at the top of the page to download an archive with the files. Otherwise click on tree to inspect the content. In the tree you will find the necessary folders and a template file called `sol002-template.yaml`.

The content of the template is as simple as:

swagger: '2.0' 
info: 
  title: NFV SOL 002 Example - SpecFest! 
  version: v1 
host: www.example.com 
basePath: /ve-vnfm 
paths: 
  # insert your paths or their json ref here 
definitions: 
  # Insert your definitions or their json ref here 

Open the given spreadsheet and tag one operation with your name

1. The operation will then be assigned to you to be edited

Editing

With offline editor

1. Open the template file with VS Code
2. Press F1, then write "Swagger preview". A new tab will open to show the graphical representation of the file. Note that as soon as you change the text, the other tab is automatically updated.

With online editor

1. Navigate to SOL002 OAS template. (Google Chrome recommended)
2. After editing, click File and then “Download YAML”

Writing the definition

Edit the OpenApi specification:

1. Look up the resource you have been assigned in NFV SOL 002
2. Create the definition into the nfv002_main_template.yaml and check correctness with VS Code
3. Cut&paste what you created into a proper resource in /paths/index.yaml and create the corresponding file
4. E.g. create the Vnf_instance data type into a Vnf_instance.yaml files
5. Configure the files so that the CI/CD validates the result

Online via Gerrit (Beginners)

• Upload the contribution via Gerrit ‘Create Change’ button
• Edit the ‘patch set’
• Paste the created files

With Git (Advanced)

1. Upload the contribution via the usual git workflow (please note the unsusual push operation endpoint)

  $ git add
  $ git commit -s -m "your message here"
  $ git push origin HEAD:refs/for/master 

Verify

1. Check Jenkins result on Gerrit and on Jenkins Job

To verify that the content of the contribution has been validated, look for the text you see in the red boxes in the picture.

1. If there is no feedback from Jenkins contact CTI
2. Wait for CTI to merge your contribution

Iterate!

All accomplished? Then it may be time to select a new part of the specification and create the OpenAPI version again!