NFV SpecFest Wiki

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

Upload an OpenAPI specification to the ETSI Forge!

Welcome to the Wiki page for the NFV SpecFest event.

The goal of the present tutorial is to create a collaborative OpenAPI specification on the ETSI Forge. The proposed activity aims at translating an extract of an ETSI NFV specification into a machine readable API description, formatted in the OpenAPIs language.

The specification used for the task will be ETSI NFV GS SOL 002 [1] and for the sake of brevity we will use a greatly simplified extract which describes the operation and data structures to be used in the task.

--> Download the SOL002 simplified extract here <--

What you need:

• A laptop (all operating system supported)
• Google Chrome browser or Opera browser installed.
• The SOL002 extract linked above.
• This wiki page.

Let's get started!

Step 0: Set up

1. Log in at ETSI Forge using your EOL account information.
2. If you do not have an account yet, you can register for a Forge account here.

Step 1: Edit the template

Make sure you are using Google Chrome or Opera as your browser from this point on.

You are now ready to edit the OpenApi specification online. Below you will find the link to the online editor which will contain a template with comments and instruction on how to fill the required information. Please note:

• If you close the Editor page, you will loose all your work.
• The template is divided in two parts: Resource paths and operations and data types definitions. You can decide to stop editing after the resources part or to continue with the data types definition.
• Once you are done editing, do not close the editor page and come back to this wiki page for the next steps.
• If you are in doubt, check the expected result at Solution (open this file in a new tab or window);

--> Template to edit <--

Step 2: Upload it to the ETSI Forge

1. Navigate to the project page of nfv-specfest
   • If required, click on the Sign in link on the top right and the page to log in with your EOL or Forge credentials.
2. Click Create Change button
   • Enter Branch: master
   • Enter Change topic: "specfest"
   • Enter Change description
   • Click on Create

How to create a new Change in the Gerrit web UI

1. Click Edit in the File list at the bottom of the page

Click edit at the bottom

1. Now click Add to insert a new modification in a file
   • Now type "upload/[your_name].yaml" and click Open button.

Click Add and insert filename

1. Copy the whole text from the Swagger Editor tab and paste the content in the newly created file.
2. Click Save and then click Close

Editing a file in the gerrit web UI

1. Now click the blue Publish edit button and then the Publish button on the top right of the page.

Click Add and insert filename

Step 3: Verify

1. Once you publish your contribution, an automatic validator will be triggered. Wait few minutes and you will see a yellow notification at the bottom right corner of the page (you will also receive notification via email). Click on it to upload the page
2. The automatic checker (under the name jenkins) will publish the result in the History Check box in the page. The entry will look like (in case of failure):

  Patch Set 2: 
  Build Failed 
  https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/18/ : FAILURE

or (in case of success)

  Patch Set 3: 
  Verified+1 Build Successful  
  https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/19/ : SUCCESS

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

In case of FAILURE

If the validation job fails you are still able to modify your contribution until it gets valid. Each time you modify the content of the contributed file, the automatic validation will be again activated and will yeld a new result.

To edit the contributed file, simply click on the file name in the Files box within the page to open the editing page again. Do not forget to save after you complete modify the text!

What to do if the validation fails

In case of SUCCESS

1. If there is no feedback from Jenkins, it will add add a label verified +1 to the contribution. This means that the contribution can be merged.
2. Contact CTI and wait for us to merge your contribution.

Congratulations, you can navigate and see your contribution at the NFV SpecFest repository!

Iterate!

The advanced version

Are you willing to take the next step? In the advanced version you will have a new template which takes the solution from the basic template and adds new elements to be filled in:

• Request parameter
• Response header
• A new data type
• Extended versions of the previous data types

As for the basic template, you are given:

• A modified extract of SOL002 with the information to fill in the template: SOL002 for advanced task

 ;

• the solution to this new task, to be checked if you feel stuck: Solution example to the advanced task.

Have fun!

--> Advanced Template <--

What now?

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

A live spreadsheet is available to keep track of "who is doing what".

• • Open the given spreadsheet and tag one operation with your name
  • The operation will then be assigned to you to be edited

Bonus level

OpenAPI v2 language reference

Find OpenAPI Specification v2: the official and complete reference of the language.

Optional: Install an offline Editor application on your system

It is possible to edit and submit the specification files directly in the browser without the need of installing anything. But that method is a bit more error prone and sometimes less comfortable, therefore a better workflow would require an Editor locally installed on your machine. We list below two different options, both free, open source and with extensions to facilitate work with OpenAPIs.

Anyway, feel free to use your preferred editor: you will need to submit only the plain text.

VS Code

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

Editing with VS Code Example

Visual Studio Code is a multiplatform, free and open source, extensible 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 correctly formatted

• 

  An example with a valid specification file

Atom Editor

1. Navigate to Atom homepage, download the installer for your platform and execute it.
2. Install the linter-swagger plugin.

Optional: Set up Git

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

Optional: Upload the contribution via Git

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

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

More on the starter kit

• A repository at the Forge, with the folder structure, a template of specification file and some examples. Click here to visit the repository.

• A live spreadsheet to keep track of "who is doing what"
  • Open the given spreadsheet and tag one operation with your name
  • The operation will then be assigned to you to be edited

References

<references />