Latest revision as of 16:26, 20 September 2017

Redirect to:

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

Log in at ETSI Forge using your EOL account information.
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:

If you close the Editor page, you will loose your work.
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.
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.
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.
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:

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.
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
Click Edit in the File list at the bottom of the page
- Click edit at the bottom
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
Copy the whole text from the Swagger Editor tab and paste the content in the newly created file.
Click Save and then click Close
- Editing a file in the gerrit web UI
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

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.
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)

Navigation menu

Difference between revisions of "NFV SpecFest Wiki"

Latest revision as of 16:26, 20 September 2017

Contribute an OpenAPI^TM specification to the ETSI Forge!

Contents

Step 0: Set up

Step 1: Edit the template

Step 2: Contribute the specification to the ETSI Forge

Step 3: Verify

In case of FAILURE

In case of SUCCESS

Congratulations

Further readings

References

@@ Line 1: / Line 1: @@
-{{stub}}
+#REDIRECT [[NFV Specfest Wiki]]
-== Upload an OpenAPI specification to the ETSI Forge! ==
+{| class="wikitable"
+|-
+| ''Dear reader, in case of missing or incorrect information on this wiki page you are welcome to contact us at cti_support@etsi.org''.
+|}
-Welcome to the Wiki page for the NFV SpecFest event.
+== Contribute an OpenAPI<sup>TM</sup> specification to the ETSI Forge! ==
-Today you have the opportunity to participate in the first collaborative OpenAPI specification on the ETSI Forge.
+Welcome to the Wiki page of the NFV Specfest event.
-We will focus our attention on [https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=49492&curItemNr=1&totalNrItems=1&optDisplay=10&qSORT=HIGHVERSION&qETSI_ALL=&SearchPage=TRUE&qETSI_NUMBER=NFV%2DSOL+002&qINCLUDE_SUB_TB=True&qINCLUDE_MOVED_ON=&qSTOP_FLG=&qKEYWORD_BOOLEAN=&qCLUSTER_BOOLEAN=&qFREQUENCIES_BOOLEAN=&qSTOPPING_OUTDATED=&butSimple=Search&includeNonActiveTB=FALSE&includeSubProjectCode=&qREPORT_TYPE=SUMMARY ETSI NFV GS SOL 002] ([http://docbox.etsi.org/ISG/NFV/Open/Drafts/SOL002_Ve-Vnfm_protocols/NFV-SOL002v051.zip Current], [http://link_to_be_done.com Release]). 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.
+The goal of the present tutorial is to create a collaborative OpenAPI<sup>TM</sup><ref>OpenAPI<sup>TM</sup> is a Trade Mark of the Linux Foundation. Find more info at [https://www.openapis.org www.openapis.org].</ref> specification on the ETSI Forge. The proposed activity aims at '''translating an extract of an [http://www.etsi.org/technologies-clusters/technologies/nfv ETSI NFV] specification into a machine readable API description, formatted in the OpenAPI<sup>TM</sup> language'''.
-What you will need:
+[[File:NFV Specfest.png|500px|frameless|center]]
-* A laptop (any operating system supported)
+The specification used for the task will be ETSI NFV GS SOL 002 [https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=49492] 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.
-* A copy (paper or PDF) of NFV SOL 002 specification
+<div class="center ext" style="width:auto; margin-left:auto; margin-right:auto;">
+<div style="font-size: 16pt">--> [https://forge.etsi.org/wiki/images/a/ac/Nfv-specfest-sol002-extract.pdf Download SOL002 example here] <--</div>
+(The link will automatically open in a new tab)
+</div>
+What you need:
+* A laptop (all operating system supported) with [https://www.google.com/chrome/index.html Google Chrome browser] or [https://www.opera.com/ Opera browser] installed.
+* The SOL002 example linked above.
 * This wiki page.
@@ Line 19: / Line 31: @@
 __TOC__
-== Set up ==
+== Step 0: Set up ==
-#  Log in at [https://forge.etsi.org/index.php/users/login ETSI Forge] inserting your EOL acconts
-#  If you do not have an account yet, simply register [https://forge.etsi.org/index.php/register here]
-=== Optional: Install an Editor application  ===
-==== VS Code ====
-#	Navigate to [https://code.visualstudio.com VS Code homepage], download the installer for your platform and execute it
-#	Install the [https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer Swagger Viewer Plugin]
-==== Atom Editor ====
-#	Navigate to https://atom.io/ Atom homepage], download the installer for your platform and execute it.
-#	Install the [https://atom.io/packages/linter-swagger linter-swagger 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 [https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git here] to visit the repository.
-* A [https://docs.google.com/spreadsheets/d/1plZ_KL1EZXRTTdcN4xZAcFFd7Ga4j66PsDI9oXki2ok/edit?usp=sharing  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:
-<pre>
-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
-</pre>
-Open the given spreadsheet and tag one operation with your name
-#  The operation will then be assigned to you to be edited
-== Editing ==
-=== Where to find documentation ===
+# Log in at <span class="ext"> [https://forge.etsi.org/index.php/users/login ETSI Forge]</span> using your EOL account information.
+# If you do not have an account yet, you can register for a ''Forge account'' [https://forge.etsi.org/index.php/register here].
+== Step 1: Edit the template ==
-=== Editing with an offline editor (VS Code) ===
+<div class="center" style="color:red;width: 83%;margin-left:auto;margin-right:auto;border: 1px solid black;margin-bottom: 20px;margin-top: 20px;">
+Make sure you are using Google Chrome or Opera as your browser from this point on.
+</div>
+<big>
+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:
-[https://code.visualstudio.com/ 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.
+# If you close the Editor page, you will '''loose your work'''.
+# 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.
+# 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.
+# 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'''.
+# If you are in doubt, check the '''expected result''' at <span class="ext">[https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git/blob_plain/HEAD:/sol002-example.yaml Solution]</span> (The link will automatically open in a new tab);
+</big>
+<div class="ext center" style="width:auto; margin-left:auto; margin-right:auto">
+<div style="font-size: 16pt">--> [https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git/blob_plain/HEAD:/sol002-template.yaml Template to edit] <--</div>
+(The link will automatically open in a new tab)
+</div>
-Find below the instructions to render OpenAPI doc in VS Code:
+== Step 2: Contribute the specification to the ETSI Forge ==
+<big>
-# Open the template file with VS Code (e.g. open or paste the template file sol002-template.yaml)
+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:
+# <span class="ext">Navigate to the project page of [https://forge.etsi.org/gerrit/#/admin/projects/nfv-specfest nfv-specfest]</span>
+#* If required, click on the <code>Sign in</code> link on the top right and the page to log in with your EOL or Forge credentials.
+# Click <code>Create Change</code> button
+#* Enter Branch: ''master''
+#* Enter Change topic: "specfest"
+#* Enter Change description
+#* Click on <code>Create</code>
+#* [[File:Gerrit-online-change-guide.png|700px|thumb|center|How to create a new Change in the Gerrit web UI]]
+# Click <code>Edit</code> in the File list at the bottom of the page
+#* [[File:Gerrit-online-change-add-new-file1.png|700px|thumb|center|Click edit at the bottom]]
+# Now click <code>Add</code> to insert a new modification in a file
+#* Now type "upload/[your_name].yaml" (e.g. "upload/jon_snow.yaml") and click <code>Open</code> button.
+#* [[File:Gerrit-online-change-add-new-file2.png|700px|thumb|center|Click Add and insert filename]]
+# Copy the whole text from the Swagger Editor tab and paste the content in the newly created file.
+# Click <code>Save</code> and then click <code>Close</code>
+#* [[File:Gerrit-online-edit-guide.png|700px|thumb|center|Editing a file in the gerrit web UI]]
+# Now click the blue <code>Publish edit</code> button and then the <code>Publish</code> button on the top right of the page.
+#* [[File:Gerrit-online-change-add-new-file2.png|700px|thumb|center|Click Add and insert filename]]
+</big>
-# 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.
+== Step 3: Verify ==
-<gallery>
+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
-Vscode-sol002-template.PNG|VS Code with the Rendered documentation in the tab on the right of the window.
-Vscode-error-reporting.PNG|VS Code will show an alert box if the file is not correcly formatted
-Vscode-valid-file.PNG|An example with a valid specification file
-</gallery>
-=== With online editor ===
+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):
-# Navigate to SOL002 OAS template. (Google Chrome recommended)
+   Patch Set 2:
-# After editing, click File and then “Download YAML”
+   Build Failed
+   https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/18/ : FAILURE
-== Writing the definition ==
+or (in case of success)
-Edit the OpenApi specification:
+   Patch Set 3:
+   Verified+1 Build Successful
+   https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/19/ : SUCCESS
-# Look up the resource you have been assigned in NFV SOL 002
+[[File:Gerrit-verify-build-hid.PNG|800px|thumb|center|To verify that the content of the contribution has been validated, look for the text you see in the red boxes in the picture.]]
-# Create the definition into the nfv002_main_template.yaml and check correctness with VS Code
-# Cut&paste what you created into a proper resource in /paths/index.yaml and create the corresponding file
-# E.g. create the Vnf_instance data type into a Vnf_instance.yaml files
-# Configure the files so that the CI/CD validates the result
-=== Online via Gerrit (Beginners)===
+=== In case of FAILURE ===
-* Navigate to the project page of [https://forge.etsi.org/gerrit/#/admin/projects/nfv-specfest nfv-specfest]
+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.
-** Click on the menu '''Projects''' -> '''List''' -> '''nfv-specfest'''
-* Click ‘Create Change’ button
-* Click 'Edit' in the File list at the bottom of the page
-* Now click "Add" to insert a new modification in a file
-** If you type the name of a file already existing in the repository, that file will be opened for editing. If otherwise you type a new file name, the file will be created.
-** As you type, gerrit will suggest names of files and folder in the repo.
-* Now click on the file to open it in the online editor.
-* Paste the content you created in your local editor or with the online editor.
-* Click Save and Close
-* Now click the blue Publish button on the top right of the page.
-<gallery>
+To edit the contributed file, simply click on the file name in the '''Files''' box within the page to open the editing page again.
-Gerrit-online-change-guide.png|How to create a new Change from gerrit web UI
+Do not forget to save after you complete modify the text!
-Gerrit-online-edit-guide.png|Editing in the gerrit web UI
-</gallery>
-=== With Git (Advanced) ===
+[[File:Gerrit-verify-build-fixed-guide.png|800px|thumb|center|What to do if the validation fails]]
-# Upload the contribution via the usual git workflow (please note the unsusual push operation endpoint)
+=== In case of SUCCESS ===
-   $ git add .
+# If there is no feedback from Jenkins, it will add a label <code>verified +1</code> to the contribution. This means that the contribution can be merged.
-   $ git commit -s -m "your message here"
+# You reached the end of the tutorial! Just wait for ETSI CTI to merge your contribution.
-   $ git push origin HEAD:refs/for/master
-== Verify ==
+=== Congratulations ===
-# Check Jenkins result on Gerrit and on Jenkins Job
+You can navigate now and see your contribution at
-[[File:Gerrit-verify-build-hid.PNG|thumb|center|To verify that the content of the contribution has been validated, look for the text you see in the red boxes in the picture.]]
+<div class="center ext" style="width:auto; margin-left:auto; margin-right:auto;">
+<div style="font-size: 16pt">--> [https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git/tree/HEAD:/upload the NFV Specfest repository] <--</div>
+(The link will automatically open in a new tab)
+</div>
-# If there is no feedback from Jenkins contact CTI
+= Further readings =
-# Wait for CTI to merge your contribution
-== Iterate! ==
+Find more on developing and contributing OpenAPI specifications at [[Describing APIs]]
-All accomplished? Then it may be time to select a new part of the specification and create the OpenAPI version again!
+= References =

Difference between revisions of "NFV SpecFest Wiki"

Latest revision as of 16:26, 20 September 2017

Contribute an OpenAPITM specification to the ETSI Forge!

Contents

Step 0: Set up

Step 1: Edit the template

Step 2: Contribute the specification to the ETSI Forge

Step 3: Verify

In case of FAILURE

In case of SUCCESS

Congratulations

Further readings

References

Contribute an OpenAPI^TM specification to the ETSI Forge!