NFV SpecFest Wiki

Dear reader, in case of missing or incorrect information on this wiki page you are welcome to contact us at cti_support@etsi.org.

Contribute an OpenAPI^TM specification to the ETSI Forge!

Welcome to the Wiki page of the NFV Specfest event.

The goal of the present tutorial is to create a collaborative OpenAPI^TM<ref>OpenAPI^TM is a Trade Mark of the Linux Foundation. Find more info at www.openapis.org.</ref> 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 OpenAPI^TM language.

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

--> Download SOL002 example here <--

(The link will automatically open in a new tab)

What you need:

• A laptop (all operating system supported) with Google Chrome browser or Opera browser installed.
• The SOL002 example 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 in the required information. Please note:

1. If you close the Editor page, you will loose your work.
2. Do not worry if you see some errors on the right part of the window: keep following the instructions in the comments and the errors will disappear.
3. The template is divided in two parts: Part 1: Resource paths and operations and Part 2: Data types definitions which refer respectively to pages 1 and 2 of the SOL002 Example given. Part 2 is optional and you can decide whether to tackle it. You will find instructions in the appropriate part of the template.
4. Once you are done editing, do not close the editor page and come back to this wiki page for the next step: Contribute the specification to the ETSI Forge.
5. If you are in doubt, check the expected result at Solution (The link will automatically open in a new tab);

--> Template to edit <--

(The link will automatically open in a new tab)

Step 2: Contribute the specification to the ETSI Forge

After you complete editing the OpenAPI file (Step 1), your next step will be contributing it on the ETSI Forge. You will be using a web interface powered by Gerrit, an open source collaboration tool. Proceed withe the points below:

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
3. Click Edit in the File list at the bottom of the page
   • 

     Click edit at the bottom
4. Now click Add to insert a new modification in a file
   • Now type "upload/[your_name].yaml" (e.g. "upload/jon_snow.yaml") and click Open button.
   • 

     Click Add and insert filename
5. Copy the whole text from the Swagger Editor tab and paste the content in the newly created file.
6. Click Save and then click Close
   • 

     Editing a file in the gerrit web UI
7. 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

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

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 yield 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 a label verified +1 to the contribution. This means that the contribution can be merged.
2. You reached the end of the tutorial! Just wait for ETSI CTI to merge your contribution.

Congratulations

You can navigate now and see your contribution at

--> the NFV Specfest repository <--

(The link will automatically open in a new tab)

Further readings

Find more on developing and contributing OpenAPI specifications at Describing APIs