NFV SpecFest Wiki

Warning: This page is a working draft. Information could be missing or unreliable. Contact the administrator for more support.

Contribute an OAS spec at ETSI Forge!

Welcome to the Wiki page for the NFV SpecFest event.

Today you have 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 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

Editing with an offline editor (VS Code)

Visual Studio Code is a multiplatform, free and open source, extendible editor by Microsoft (similar to SublimeText and Atom Editor). For VS Code a handy plugin is available to render OpenAPIs documentation while typing, therefore we selected this as a suitable tool for our activity. Anyway, feel free to use your preferred editor for the task.

Find below the instructions to render OpenAPI doc in VS Code:

1. Open the template file with VS Code (e.g. open or paste the template file sol002-template.yaml)

1. Press F1, then write "Swagger preview" and hit Enter. 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.

• 

  VS Code with the Rendered documentation in the tab on the right of the window.

• 

  VS Code will show an alert box if the file is not correcly formatted

• 

  An example with a valid specification file

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!