In addition to the industry-standard metadata formats like WSDL, XSD, Swagger and JSON Schemas, Sentinet allows attachment of a non-conventional metadata in the form of:
These attachments can be added to services and APIs to provide additional documentation, references and tags to describe, document and categorize registered services. Attachments can also be added to Access Rules and Service Agreements.
Metadata attachments can be applied to physical, and virtual services at different attachment levels. These attachment levels are:
REST service versions may use Links, Keyword Tags and Description Tags in the Swagger documents generated for the service version.
To provide service-level attachments, select a service element in the Repository tree.
For all other levels of service attachments, select the appropriate service element of the service version tree and click the ATTACHMENTS tab.
Attachments can be added to the following Repository items:
- Service Version (at different levels)
- Access Rule
- Service Agreement
- Custom Entity
Links and Files
To add links and files, click the [+ Add] button in the Attachment table. In the Add Attachment dialog, provide a description for your attachment and select the Link or File radio button.
Link can be any valid Uri that points to an internet or intranet resource. For example, a public URL to an API documentation, or a URL to a file in a Source Control System.
Any file can be uploaded and stored in the Repository database, providing it is less than 10GB in size.
Once links or files are added as attachments, a user can click on them in the VALUE column to open links or download files.
Keyword Tags serve the purpose of tagging services and service elements for additional categorization. They are also used in the generated Swagger/OpenAPI documents. To add a Keyword Tag, click the [+ Add] button.
Description Tags create descriptive name-value pairs that are attached to the selected service tree element(s). For REST APIs specifically, these name-value pairs will appear in the generated Swagger/OpenAPI document (see Service Version Metadata chapter for REST APIs for more details on Swagger documentation). To add a Description Tag, click the [+ Add] button and type in a tag name and its description.
Once attachments are saved, Description Tags will show as name-value pairs.
There is one special Description Tag, Swagger::OperationSummary that offer smooth integration with REST API Swagger/OpenAPI. The value of this Description tag identifies Swagger/OpenAPI operation’s summary. When defined in Sentinet, it will be exported as Swagger operation’s summary. When imported from a Swagger document, it will be added as a Description Tag with the tag Swagger::OperationSummary and Description value as operation’s summary.
Searching Repository by Tags
Repository can be searched for any registered in it entity (see chapter Repository Search in this document for more details).
When searching by Keyword Tags specifically, you can place more than one tag in the Tags advanced search field separated by semicolon. For example: tag1;tag2. Each tag must match exact tag name (ignoring upper/lower case) and all searched tags must be attached to an entity if more than one tag is specified in the search criteria.
When searching by Description Tags specifically, you can place more than one description tag in the Tags advanced search field separated by semicolon. Each Description must be entered as tag=description pair. For example: MyDescriptionTag1=123; MyDescriptionTag2=567. Each description tag must match exact tag name and value (ignoring upper/lower case) and all searched tags must be attached to an entity if more than one tag is specified in the search criteria.