To ease our way into composing the full API specification, let's start with the simplest endpoint—GET /salt. To start off, we will add the paths root property, specify the path we are defining (/salt), and then the operation (get):

paths:
  /salt:
    get:

Under the get property, we will define an operation object. The full specification for the Operation Object can be found at github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operation-object. For our use cases, we are concerned with the following properties:

• tags: This is used to logically group operations when displayed with Swagger UI.
• summary: A short summary of what the operation does.
• description: A more verbose description of the operation, which may include nuances that a developer might need to be aware of.
• parameters: A parameter object that describes what parameters are allowed/required, and how these parameters should be provided (such as URL parameters, query strings, headers, or cookies).
• requestBody: A request body object that describes the body of the request, if any. It describes what types of payloads are allowed (for example, application/json, text/plain), and, if it is an object, what data type and formats each property should be.
• responses: A Responses Object that describes all possible responses this endpoint can produce.

So, let's start with the simpler fields: tags, summary, and description:

paths:
  /salt:
    get:
      tags:
        - Authentication
      summary: Returns the salt of a user based on the user's email
      description: Even if there are no users with the specified email, this endpoint will still return with a salt. This is to prevent the API leaking information about which email addresses are used to register on the platform.