Carignani: /* Optional: Install an offline Editor application on your system */

2018-02-28T08:53:50Z

Optional: Install an offline Editor application on your system

← Older revision		Revision as of 10:53, 28 February 2018
Line 21:		Line 21:
	Find [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI Specification v2]: the official and complete reference of the language.		Find [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI Specification v2]: the official and complete reference of the language.

	== ~~Optional:~~ Install an offline Editor application on your system ==		== 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.		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.

Carignani: Created page with "== Advanced tutorial == You took part in the ETSI NFV SpecFest and are willing to take the next step? In the advanced advanced you will have a new template which takes the so..."

2017-08-29T13:34:18Z

Created page with "== Advanced tutorial == You took part in the ETSI NFV SpecFest and are willing to take the next step? In the advanced advanced you will have a new template which takes the so..."

New page

== Advanced tutorial ==

You took part in the ETSI NFV SpecFest and are willing to take the next step? In the advanced advanced 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:
* An advanced SOL002 example with the information to fill in the template: <span class="ext"> [https://forge.etsi.org/wiki/images/e/ea/Nfv-specfest-sol002-extract-advanced.pdf <big>SOL002 for advanced task</big>]</span> ;
* the solution to this new task, to be checked if you feel stuck: [https://forge.etsi.org/rep/gitweb.cgi/nfv-specfest.git/blob/HEAD:/sol002-example-advanced.yaml <big>Solution example to the advanced task<big>].

Have fun!

<div class="ext center" style="width:auto; margin-left:auto; margin-right:auto;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-advanced.yaml Advanced Template] <--
</div>

== OpenAPI v2 language reference ==

Find [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md 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 ===

# 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]

=== Editing with VS Code Example ===

[https://code.visualstudio.com/ 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:

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

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

<gallery>
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>

=== 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]].

=== Optional: Upload the contribution via Git ===

# 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 [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

Describing APIs - Revision history

Carignani: /* Optional: Install an offline Editor application on your system */

Carignani: Created page with "== Advanced tutorial == You took part in the ETSI NFV SpecFest and are willing to take the next step? In the advanced advanced you will have a new template which takes the so..."