Describing APIs

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

OpenAPI v2 language reference

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

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 VS Code homepage, download the installer for your platform and execute it
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:

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.

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

Navigate to Atom homepage, download the installer for your platform and execute it.
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

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

Navigation menu