Spec Designer
API Spec Creator allows creating a new API Definition Document (API Spec) by entering data through forms, or using existing API Definition Documents by importing them. These API Definition Documents can then be used to create API Proxies.
Please refer to https://swagger.io/specification/ for a detailed explanation of the information entered through the API Spec Editor.
API Spec List
When the Spec Designer link is clicked from the main menu, the list of API Specs is displayed.
At the top of the list are the filter fields. When the filter fields are updated, the list content is also updated according to the filter.
Creating an API Spec
It is used to design an API that does not exist, or to create documentation for APIs that have been developed with a code-first approach and do not have any definition documents.
A new API Spec can be created by clicking the 
Create button at the top right of the list interface.
There are two options when creating a new API Spec.
Creating API Spec by Filling a Form
When the new API Spec interface is opened, it is seen that the Blank API option is selected from the two existing options by default.
The API Spec Creator fields are shown in the table below.
| Field | Description |
|---|---|
Title | The title/name of the API Spec that appears in the list. It is mandatory and must be unique on a project basis. |
Description | Optional description of the API Spec. |
Servers | It is the list of servers that the API serves/will serve. |
| Server - URL | The address where the API can be accessed. It is mandatory. |
Server - Description | The description for the server. It is optional. |
After the Title field is filled and at least one server record is created in the Servers section, the Create button in the upper right is enabled and the spec can be saved by clicking this button. Operations that can be done after saving the definition file are explained in the Updating an API Spec section.
Importing an existing API Spec
The second option to create a new API Spec is to import an existing API Spec. For this, the Import API Spec option is selected.
The two standards supported for importing are OpenAPI 3.0.x and OpenAPI 2.x (Swagger) standards.
There are the Enter URL and Upload File options to import the file conforming to the selected standard.
Use Spec Authorization
Some definition files check that the client is authorized so that their content can be viewed. For this, authentication data must be sent within the HTTP request. If the definition file in the URL to be accessed is such a file, this box is checked and the credentials are entered.
If the Use Spec Authorization option is checked, the table below appears and the keys required for authorization are added.
Enter URL
The address where the existing API Spec file can be accessed is entered in the URL field and the Parse button is clicked.
Upload File
The Upload button is clicked, the existing API Spec file is selected and uploaded, and the Parse button is clicked.
In both methods, the results of the parsing process are Title, Description and Servers fields. Unlike creating an empty API, the values for these fields are retrieved from the imported API Spec file. After this step, the Create button at the top right is enabled and the definition file can be saved by pressing this button. Operations that can be done after saving the definition file are explained in the Updating an API Spec section.
Updating an API Spec
The API Spec update interface opens when the value in the Title column of a record is clicked in the API Spec list or the Edit option is selected on the menu at the rightmost column of that record.
The picture below shows the settings of the API Spec:
API Overview
When the update interface is opened, the API Overview appears. The API Overview link is on the left side of the interface.
Paths
Just below the API Overview link is the Paths section.
Path is the name given to each of the addresses of an API to which a request can be sent.
Adding a Path
In order to add a new Path to the existing ones, the (New Path) button in the heading of the Paths section is clicked.
In the popup, the Path to be added is entered and the Save button is clicked.
Deleting a Path
When any one of the addresses in the list is clicked, that address is selected and a section where the details of that address can be managed is displayed on the right. The address can be deleted by clicking the Delete button at the top right of this section.
Updating a Path
When any one of the addresses in the list is clicked, that address is selected and a section where the details of that address can be managed is displayed on the right.
Changing the Path
At the top on the right, the Path is displayed as a link. When the Edit button next to this link is clicked, the address can be updated from the pop-up window.
The picture below shows the settings of the editing a path:
Operations
When a Path is selected, a section on the right side of the interface where the Operations defined for that address can be managed.
Operation: It consists of each valid HTTP Method that an API accepts requests through its defined addresses, and the identity and identifying information, parameters, request and response contents of this method.
When any Path is selected, the first of the Operations defined for that Path is displayed as selected.
The selected Operation is indicated by the thin blue line at the bottom of the box containing the HTTP Method name.
In the image above, the /pet/findByStatus address has been selected by the user, and the Get operation defined for this Path is automatically selected and its details are displayed.
Identity and Identification Fields
The fields used for the Identity and Identification Fields are shown in the table below.
| Field | Description |
|---|---|
Summary | An optional brief description of what the Operation does. |
Operation ID | The key of the operation. It must be unique among all operations of the API. It is case-sensitive. It is RECOMMENDED that common programming naming conventions be followed, as tools and libraries can use this value to uniquely identify a process. |
Description | An optional detailed description of Operation's behavior. |
Tags | Tags can be used to logically group processes by resources or other qualifiers. It is optional and can be added more than once. |
Header Parameters
This is the section where the headers that can be sent to this Operation are managed.
Query Parameters
This is the section where the query parameters that this Operation can receive are managed.
Request Body
This is the section where sample request bodies for this Operation can be managed. A sample request body can be defined for one or more Media Types.
Responses
This is the section where the Responses that can be returned by this Operation can be managed.
Each response consists of an HTTP Status Code, a description of that status code, and a Response Body for one or more Media Types.
Apinizer allows defining multiple possible response bodies for a Media Type and the conditions under which they can be returned.
The following image shows:
- 200 and 400 codes can be returned by this Operation.
- For the 200 code, two different Media Types can be returned as application/json or application/xml.
- For the application/json Media Type, it will return a response body similar to the first line if the value of status parameter is "pending", or similar to the second line if the parameter's value is "sold".
Adding an Operation
When a Path is selected, the Operations defined for that Path are displayed with the corresponding HTTP Methods colored. For uncolored HTTP Methods, an Operation has not yet been defined. If an Operation is desired to be defined for any of these, the HTTP Method is selected. With this selection, it appears that no Operation has been defined for the selected method yet, and a new one can be added by pressing the Add Operation button.
Deleting an Operation
When an Operation is selected, a Delete button appears on the right side of the window. The selected Operation can be deleted by clicking this button.
Data Models
At the bottom of the left side of the interface, data models used by this API and which that are not standard primitive types are displayed.
Adding a Data Model
The New Data Model button to the under of the section title is clicked to add a new data model.
In the popup, enter the name and description of the data model and click the Save button.
Importing a Data Model
Models added to the Data Models in the Spec can be transferred via the Data Models page.
Deleting a Data Model
When you click on any data model, the details of that data modelare displayed on the right. The data modelcan be deleted by clicking the Delete button in the upper right part of this opened section.
Updating a Data Model
When on any data model is clicked, the details of that data model are displayed on the right. This section contains the name, description, and properties of the data model.
Changing the Name of the Data Model
Clicking the icon next to the name of the Data Model opens a text box where the name can be updated.
Properties
Each of the attributes of the Data Model is called a Property. A Data Model can be viewed as a Class in Object Oriented Programming, and a Property as a property or an attribute within that class.
Adding a Property
Clicking the button on the right of the column headings of the Properties table opens a popup where a new Property can be added.
The Save button is clicked after the data fields in the popup are filled.
The Property fields are shown in the table below.
| Field | Description |
|---|---|
Name | The name of the feature. It is mandatory and must be unique within the Properties of the Data Type. |
Description | It is an optional explanation of what the feature is and how to use it. |
Required | Indicates whether the value of this property is required. |
Type | The data type of the Property. Basic types or types defined for the API can be used. It is mandatory. |
Deleting a Property
Each feature in the features table has a Remove button that can be used to delete that feature from the menu at the end of the line.
Updating a Property
If the value in the Name column of any of the properties is clicked, a popup will appear where that property can be updated. After the updates are made, the update process is completed by pressing the Save button.
Deleting an API Spec
The record can be deleted by clicking the menu button in the rightmost column of the record to be deleted in the API Definition Document list and selecting Remove.
Creating an API Proxy using API Spec
An API Proxy can be created using this API Spec by clicking the Create API Proxy button in the update interface of the API Definition Document.
When creating an API Proxy using an API Spec, the definitions in the spec file are used as a template for the API Proxy. After the API Proxy is created, the changes made in the definition file through the API Spec Creator do not affect the API Proxy, and the changes made in the Design tab of the API Proxy do not affect the original API Spec used during creation.
Multiple API Proxies can be created using the same API Spec.