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 accounts
-#  If you do not have an account yet, simply register [https://forge.etsi.org/index.php/register here]
-=== Optional: Install an Editor application  ===
-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 ====
-#	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 start up the activity we provided:
-* A repository at the Forge, with the folder structure, a template of specification file 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"
-** Open the given spreadsheet and tag one operation with your name
-**  The operation will then be assigned to you to be edited
-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" linke to inspect the content. In the ''tree'' page 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>
-== Editing ==
-=== Where to find documentation ===
-* The official reference of [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI Specification v2]
-* Templates and examples in our [https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git/tree nfv-specfest repository]
-=== Editing with an offline editor: VS Code Example ===
+# 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].
-[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.
+== Step 1: Edit the template ==
-Find below the instructions to render OpenAPI doc in 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:
-# Open the template file with VS Code (e.g. open or paste the template file sol002-template.yaml)
+# 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>
+== Step 2: Contribute the specification to the ETSI Forge ==
+<big>
+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:
-# 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.
+# <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]]
-<gallery>
+</big>
-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 correctly formatted
-Vscode-valid-file.PNG|An example with a valid specification file
-</gallery>
-=== With the online editor ===
+== Step 3: Verify ==
-Note: Using Google Chrome as a browser is recommended for this procedure
+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
-# Navigate to SOL002 OAS template.
+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):
-# After editing, click File and then “Download YAML”
-== Writing the definition ==
+   Patch Set 2:
+   Build Failed
+   https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/18/ : FAILURE
-Edit the OpenApi specification:
+or (in case of success)
-# Look up the resource you have been assigned in NFV SOL 002
+   Patch Set 3:
-# Create the definition into the nfv002_main_template.yaml and check correctness with VS Code
+   Verified+1 Build Successful
-# Cut&paste what you created into a proper resource in /paths/index.yaml and create the corresponding file
+   https://forge.etsi.org/jenkins/job/nfv-specfest-merge-and-validate/19/ : SUCCESS
-# E.g. create the Vnf_instance data type into a Vnf_instance.yaml file
-# Configure the files so that the CI/CD validates the result
-=== Online via Gerrit (Beginners)===
+[[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.]]
-* Navigate to the project page of [https://forge.etsi.org/gerrit/#/admin/projects/nfv-specfest nfv-specfest]
+=== In case of FAILURE ===
-** 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>
+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.
-Gerrit-online-change-guide.png|How to create a new Change from gerrit web UI
-Gerrit-online-edit-guide.png|Editing in the gerrit web UI
-</gallery>
-=== With Git (Advanced) ===
+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!
-# Upload the contribution via the usual git workflow (please note the unususual push operation endpoint)
+[[File:Gerrit-verify-build-fixed-guide.png|800px|thumb|center|What to do if the validation fails]]
-   $ git add .
+=== In case of SUCCESS ===
-   $ git commit -s -m "your message here"
-   $ git push origin HEAD:refs/for/master
-== Verify ==
+# 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.
+# You reached the end of the tutorial! Just wait for ETSI CTI to merge your contribution.
-# Check Jenkins result on Gerrit and on Jenkins Job
+=== Congratulations ===
-[[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.]]
+You can navigate now and see your contribution at
-# If there is no feedback from Jenkins contact CTI
+<div class="center ext" style="width:auto; margin-left:auto; margin-right:auto;">
-# Wait for CTI to merge your contribution
+<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>
-== Iterate! ==
+= Further readings =
-All accomplished? Then it may be time to select a new part of the specification and create the OpenAPI version again!
+Find more on developing and contributing OpenAPI specifications at [[Describing APIs]]
-= TODO =
+= References =
-* use only the online editor
-* first run is done by presenter
-* They can reproduce what the presenter did or choose a new operation
-* insert a complete example with one operation (the solution)
-* make the offline editors and git a BONUS at the bottom
-* inserted screenshots in the wiki on how to to step by step
-* more clear and repeated link to SPEC + bring a paper version of an extract (need to make it) after installation part
-* no link to portal page
-* instructions for vs code plugin are not correct
-* provide examples in wiki as screenshots
-* fix the snapshot operation
-* Just point to the online editor
-* send email with
-** printout and link to specs
-** install google chrome
-** install git and offline editors if you need
-* right click to get the snapshot
-* fix NFV meeting ID in readme of the repository
-* put again link to handy plugins for vs code
-* fix all links to repositories so that they refer to the tree page
-*

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!