Searching SwaggerHub

Last modified on May 06, 2021

Use SwaggerHub Search to find APIs and domains by name, content, status, or other attributes. Anonymous users can search among all public definitions. Logged in users can also search among the private definitions they have access to.

MY hub, organization pages and project pages also have a search bar with the search scope limited accordingly.

The search is performed only among the default versions of APIs and domains.

Searching SwaggerHub

Click the image to enlarge it.

Text search

Search terms are case-insensitive and are matched against:

  • YAML contents of API definitions and domains,
  • info.title and info.description in definitions,
  • API and domain names,
  • owner names.

SwaggerHub uses full text search. Search queries work as follows:

  • Queries containing multiple terms such as pet store find definitions containing all of these terms anywhere in the definition. This is equivalent to using the boolean AND operator: pet AND store.

  • Each term is matched as a substring. For example, book will find book, eBook, bookstore, booking, and so on.

  • Stop words and words less than 3 characters long are ignored. For example, the search string get a report is converted to report: the word "get" is ignored as a stop word, and "a" is ignored due to its length.

  • The characters + - | are stripped – both during indexing and at search time. All other characters are searchable. For example:

    • 111222, 111-222, 11+12+22, 11122|2 are considered to be the same string. Any of these search strings will find all of them.

    • The search string /users/{id} will find this literal string.

  • Phrase search using quotation marks (such as "hotel booking") is not supported. Quotation marks do not have special meaning and are treated as regular word characters.

  • Parentheses ( ) do not affect the precedence in boolean expressions. Parentheses are treated as regular word characters.

Boolean operators

You can combine the search terms using boolean operators to expand or narrow down your search. These operators must be uppercase.

AND (default)

Find definitions that contain both terms anywhere.

OR

Find definitions that contain either term.

NOT

Exclude definitions that contain the term after NOT.

Examples:

Search terms are case-insensitive and are matched against:

  • YAML contents of API definitions and domains,
  • info.title and info.description in definitions,
  • API and domain names,
  • owner names.

SwaggerHub uses full text search. Search queries work as follows:

  • Queries containing multiple terms such as pet store find definitions containing all of these terms anywhere in the definition. This is equivalent to using the boolean AND operator: pet AND store.

  • Each term is matched as a substring. For example, book will find book, eBook, bookstore, booking, and so on.

  • Stop words are ignored. For example, the get a report search string is converted to a report because "get" is ignored as a stop word.

  • The following special characters are ignored and replaced with spaces:

    + - = & | > < ! ( ) { } [ ] ^ " ~ * ? : \ /

    For example, the search string /users/{id} is converted to users id (which in turn is equivalent to users AND id).

  • The exact phrase search (such as "hotel booking") is not supported.

Boolean operators

You can combine the search terms using boolean operators to expand or narrow down your search. These operators must be uppercase.

AND (default)

Find definitions that contain both terms anywhere.

OR

Find definitions that contain either term.

NOT

Exclude definitions that contain the term after NOT.

Examples:

Search terms are case-insensitive and are matched against:

  • info.title and info.description in definitions,
  • API and domain names,
  • owner names.
Note: v. 1.26 and earlier do not search the YAML contents of APIs and domains. Full text search is available since v. 1.27.

A query containing just one term searches for this term as a substring. For example, book will find book, eBook, bookstore, booking, and so on.

Multiple words, such as petstore server, are treated as an exact substring search – all the words in that exact order. You do not need to enclose the phrase in quotation marks.

Filter keywords

Search queries can include the following keywords to filter the search results.

type:api

Find APIs only.

type:domain

Find domains only.

 

spec:openapi3.0

Find OpenAPI 3.0 definitions.

spec:swagger2.0

Find OpenAPI 2.0 definitions.

 

owner:name

Find APIs and domains owned by the specified user or organization. Owner names are case-sensitive.

 

visibility:public

Find public APIs and domains.

visibility:private

Find private definitions owned by you or shared with you. You must be logged in to use this option.

 

state:published

Find published definitions only.

state:unpublished

Find unpublished definitions only.

 

standardization:failed

Find APIs with standardization errors or warnings.

standardization:critical

Find APIs with standardization errors.

standardization:warning

Find APIs with standardization warnings.

Note for SwaggerHub On-Premise users: standardization:critical and standardization:warning are supported since v. 1.23.

Examples

Notes:

  • There must be no spaces after the prefixes: owner:fehguy is valid, owner: fehguy is not.

  • Multiple keywords with the same prefix, such as owner:fehguy owner:kesh92, are not supported. The last one will be used.

Sorting

Search results can be sorted to display them in a specific order. The sort options are:

  • best match (relevance),
  • update date,
  • creation date,
  • API or domain name,
  • API or domain title (info.title),
  • owner name.
Sorting

In SwaggerHub SaaS and SwaggerHub On-Premise 1.27, the default sort order is Best Match which ranks the results based on where the search terms appear in the definition. The priority is as follows:

  1. The term appears in the definition name.

  2. The term appears in the info.title.

  3. The term appears in the info.description.

  4. The term appears elsewhere in the YAML content.

Stop words

This information applies to SwaggerHub SaaS and SwaggerHub On-Premise 1.27.

Stop words are common words that frequently appear in the text and, therefore, would return many non-relevant results. For example, all OpenAPI definitions contain info, title, version and other standard keywords, so these words themselves are not useful for search. When searching, stop words are ignored to improve search performance.

The following OpenAPI keywords are considered stop words and are not searchable:

$method, $ref, $request, $response, $statusCode, $url, additionalProperties, allOf, allowEmptyValue, allowReserved, anyOf, apiKey, array, attribute, authorizationCode, authorizationUrl, basePath, basic, bearer, bearerFormat, binary, body, boolean, byte, callbacks, clientCredentials, collectionFormat, components, consumes, contact, content, contentType, cookie, csv, date, date-time, deepObject, default, definitions, delete, deprecated, description, discriminator, double, email, encoding, enum, example, examples, exclusiveMaximum, exclusiveMinimum, explode, externalDocs, externalValue, false, float, flow, flows, form, format, formData, get, head, header, headers, host, http, https, implicit, in, info, int32, int64, integer, items, label, license, links, mapping, matrix, maximum, maxItems, maxLength, maxProperties, minimum, minItems, minLength, minProperties, multi, multipleOf, name, namespace, not, null, nullable, number, oauth2, object, oneOf, openIdConnect, openIdConnectUrl, openapi, operationId, operationRef, options, parameters, password, patch, path, pathitems, paths, pattern, pipeDelimited, pipes, post, prefix, produces, properties, propertyName, put, query, readOnly, refreshUrl, requestBodies, requestBody, required, responses, schema, scheme, schemes, scopes, security, securityDefinitions, securitySchemes, server, servers, simple, spaceDelimited, ssv, string, style, summary, swagger, tags, termsOfService, title, tokenUrl, trace, true, tsv, type, uniqueItems, url, value, variables, version, wrapped, writeOnly, xml

Highlight search results