[Skip to the steps if you are keen to start the configurations] Happy Automations
Senya Editor for VS Code supports OpenAPI 3.0 and Swagger 2.0 completion snippets for YAML and JSON files. Swagger has a range of tools for API design solutions for a variety of contributors: individual developers, API Architects, teams, and enterprise organizations.
The first question should be the need for an editor when there are inbuilt ‘add-ons’. Soon after the installation of HA, you would start personalising your home automation by editing the configuration.YAML(for those configs not yet supported by the User Interface). The HA community is generously contributing to enhancing the product capability and soon we should have all configurations through the UI]. Until then for a few tweaks, we need the manual edits and the file is going to get bigger and difficult to manage through the ‘add-on’ file editors, IMHO.
Now, why notepad++ over other standalone editors? It is free, support multiple encodings, highlight syntax for multiple languages (not everyone speaks English in good sense) lightweight, plugins of-course and save versions locally.
The HA community forum is constantly updated and so I recommend searching there for all questions. Here I collate the minimal steps for you to start your edits. There are a few sources on the setup but for the end to end configurations. So, the steps below will be of help. A video would have been easier than this doc and I will try to come up with one shortly. Here you go for now.
My current HA version:0.111.4
Step 1: Install the following
a) Terminal & SSH addon on HA; Supervisor à Add-on Store à Terminal & SSH
b) PuTTY Software for your PC OS version [Win10 64bit for this example]
c) Notepad++ for your PC OS version
Step 2: Configure Putty
Although there are a couple of ways, I am mentioning here the secure way of access which is SSH using private keys. Accessing the HA is then possible only if there is access to this local file.
a) When you downloaded Putty, it should have downloaded the PuTTYgen as well. Open this, hit ‘generate’ and move the mouse a few times until it generates a key. Then type in a Key passphrase, confirm key passphrase at the respective fields and then download and save the ‘private key’ to the local machine. DO NOT close the window yet.
Notepad++ cannot open the SSH private key we created, unlike WinSCP. So, we need to create an onetime open SSH private key. Hit the ‘Conversions’ on the command tab and select ‘Export Open SSH Key’. Choose a file name and save the ‘Open SSH private key’ to the local machine
b) Now go to the Supervisor on the Home Assistant UI and open the ‘Terminal & SSH’. On the ‘Configuration’ section, copy the key generated in the above step and hit save. In the Network section just below enter ‘22’ as the port value and save.
Go back to the Info section and restart the ‘Terminal & SSH’ add-on.
c) Now open the Putty. Enter your Raspberry IP address (find this from the router, static IP or using apps like IP tools). SSH runs on port 22. Then expand the Category ‘SSH’ on the left and select ‘Auth’. Browse for the private key that we saved in the previous step but DO NOT hit ‘open’ yet.
Go back to Category ‘Session’ and ‘Save’ the setting for ‘Load’ next time. Hit ‘Open’ and you might get some prompting windows. Hit ‘yes’
d) You see the terminal now connected to the Raspberry Pi running the HassIO. Login will be ‘root’ and then enter the passphrase we gave in this section (a). At this stage, the terminal can communicate with the Home Assistant and files could be opened and edited. But we need to edit and manage the files in a user-friendly way through Notepad++. So, let's continue to the last step of configuring the Notepad++.
Step 3: Configure Notepad++
a) Open Notepad++ and select Pluginsà Plugins Admin and search for NppFTP and install this. Notepad++ will restart and you might have a new window to the right. If it is not visible select PluginsàNppFTPàShow NppFTP window.
b) In the NppFTP window, you have an icon for ‘Setting’ and open ‘Profile Settings’. Select ‘Add new’ then give a name. I gave as HASSIO and complete the fields like below
Then go to the ‘Authentication’ tab and make changes like below. We need to select the ‘Open SSH private key’ that we created in step 2 (a) here and provide the same passphrase we created an close the ‘Profile Settings’
c) Select the (Dis)Connect icon in the NppFTP Window and select the Profile we just created. You can see towards the bottom of the notepad++ window, the connection progress and response. On a successful connection, you will have the Home Assistant files listed in the NppFTP window and you are all set to browse and edit them in Notepad++
Before we dive into the steps of the OpenAPI Tutorial, it will help to have a better grounding in YAML, since this is the most common syntax for the OpenAPI specification document. (You can also use JSON, but the prevailing trend with the OpenAPI document format is YAML.)
YAML stands for “YAML Ain’t Markup Language.” This means that the YAML syntax doesn’t have markup tags such as < or >. Instead, it uses colons to denote an object’s properties and hyphens to denote an array.
Working with YAML
YAML is easier to work with because it removes the brackets, curly braces, and commas that get in the way of reading content.
YAML is an attempt to create a more human-readable data exchange format. It’s similar to JSON (which is actually a subset of YAML) but uses spaces, colons, and hyphens to indicate the structure.
Many computers ingest data in a YAML or JSON format. It’s a syntax commonly used in configuration files and an increasing number of platforms (like Jekyll), so it’s a good idea to become familiar with it.
YAML is a superset of JSON
For the most part, YAML and JSON are different ways of structuring the same data. Dot notation accesses the values the same way. For example, the Swagger UI can read the openapi.json or openapi.yaml files equivalently. Pretty much any parser that reads JSON will also read YAML. However, some JSON parsers might not read YAML because there are a few features YAML has that JSON lacks (more on that below).
YAML syntax
With a YAML file, spacing is significant. Each two-space indent represents a new level:
Each new level is an object. In this example, the level1 object contains the level2 object, which contains the level3 object.
With YAML, you generally don’t use tabs (since tab spacing is non-standard). Instead, you space twice.
Each level can contain either a single key-value pair (also referred to as a dictionary in YAML lingo) or a sequence (a list of hyphens):
The values for each key can optionally be enclosed in quotation marks. If your value has a colon or quotation mark in it, enclose it in quotation marks.
Comparing JSON to YAML
Earlier in the course, we looked at various JSON structures involving objects and arrays. So let’s look at the equivalent YAML syntax for each of these same JSON objects.
Best Editor For Kubernetes Yaml
You can use Unserialize.me to make the conversion from JSON to YAML or YAML to JSON.
Here are some key-value pairs in JSON:
Here’s the same structure expressed in YAML syntax:
Here’s an array (list of items) in JSON:
In YAML, the array is formatted as a list with hyphens:
Here’s an object containing an array in JSON:
Here’s the same object with an array in YAML:
Here’s an array containing objects in JSON:
Here’s the same array containing objects converted to YAML:
Hopefully, by seeing the syntax side by side, it will begin to make more sense. Is the YAML syntax more readable? It might be difficult to see in these simple examples, but generally it is.
JavaScript uses the same dot notation techniques to access the values in YAML as it does in JSON. (They’re pretty much interchangeable formats.) The benefit to using YAML, however, is that it’s more readable than JSON.
However, YAML might be more tricky because it depends on getting the spacing just right. Sometimes that spacing is hard to see (especially with a complex structure), and that’s where JSON (while maybe more cumbersome) is perhaps easier to troubleshoot.
Some features of YAML not present in JSON
YAML has some features that JSON lacks. You can add comments in YAML files using the # sign. YAML also allows you to use something called “anchors.” For example, suppose you have two definitions that are similar. You could write the definition once and use a pointer to refer to both:
If you access the value, the same definition will be used for both. The *apidef acts as an anchor or pointer to the definition established at &apidef.
You won’t use these unique YAML features in the OpenAPI tutorial, but they’re worth noting because JSON and YAML aren’t entirely equivalent. For details on other differences between JSON and YAML, see Learn YAML in Minutes. To learn more about YAML, see this YAML tutorial.
YAML is also used with Jekyll. See my YAML tutorial in the context of Jekyll for more details.
JSON versus YAML for the spec format
Let’s clear up some additional descriptors around JSON and YAML as well. The specification document in my OpenAPI tutorial uses YAML (which I introduced briefly here), but it could also be expressed in JSON. JSON is a subset of YAML, so the two are practically interchangeable formats (for the data structures we’re using). Ultimately, though, the OpenAPI spec is a JSON object. The specification notes:
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. (See Format)
In other words, the OpenAPI document you create is a JSON object, but you have the option of expressing the JSON using either JSON or YAML syntax. YAML is more readable and is a more common format (see API Handyman’s take on JSON vs YAML for more discussion), so I’ve used YAML exclusively in code samples here. You will see that the OpenAPI specification documentation on GitHub always shows both the JSON and YAML syntax when showing specification formats. (For a more detailed comparison of YAML versus JSON, see “Relation to JSON” in the YAML spec.)
YAML refers to data structures with three main terms: “mappings (hashes/dictionaries), sequences (arrays/lists) and scalars (strings/numbers)” (see “Introduction” in YAML 1.2). However, because the OpenAPI spec is a JSON object, it uses JSON terminology — such as “objects,” “arrays,” “properties,” “fields,” and so forth. As such, I’ll be showing YAML-formatted content but describing it using JSON terminology.
Cached
Review and summary
So that we’re on the same page with terms in the upcoming tutorial, let’s briefly review. Each level in YAML (defined by a two-space indent) is an object. In the following code, california is an object. animal, flower, and bird are properties of the california object.
Here’s what this looks like in JSON:
The specification often uses the term “field” in the titles and table column names when listing the properties for a specific object. (Further, it identifies two types of fields — “fixed” fields are declared, unique names while “patterned” fields are regex expressions.) Fields and properties are used synonymously in the OpenAPI spec.
In the following code, countries contains an object called united_states, which contains an object called california, which contains several properties with string values:
In the following code, demographics is an object that contains an array:
YAML - Visual Studio Marketplace
Here’s what the above code looks like in JSON:
Hopefully, those brief examples will help align us with the terminology used in the tutorial.
Let’s get started
Best Editor For Yaml Files
With that information about YAML, hopefully the upcoming step-by-step sections that walk through each section in the OpenAPI spec, using YAML as the primary format, will make more sense. Let’s get started with Step 1: The openapi object (OpenAPI tutorial).
Yaml-language-server Acts As A Language Serverand Analyze Your YAML In Separate Process
49/162 pages complete. Only 113 more pages to go.