Swagger Studio

https://support.smartbear.com/swagger/studio/docs/
Admin
Swagger Studio is an API design and development tool that allows users to create, edit, and validate...
Tokens:117,164
Snippets:816
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### API Request Example with Query Parameters

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

This example shows a GET request to an API endpoint that includes query parameters for 'limit' and 'offset'. These parameters are used to control the pagination of results, allowing clients to specify the number of items per page and the starting page. This reduces server load by not returning unnecessary data.

```http
GET https://example.io/v1/artists?limit=20&offset=3
```

--------------------------------

### Example GET Request URL with Query Parameters

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

This example shows a URL that utilizes query parameters to fetch a list of artists. The 'limit' parameter is set to 20, requesting 20 items, and the 'offset' parameter is set to 3, indicating the third page of results should be returned. This is a common pattern for pagination.

```http
GET http://example.com/v1/artists?limit=20&offset=3
```

--------------------------------

### Examples of Valid Version Numbers

Source: https://support.smartbear.com/swagger/studio/docs/en/manage-apis/versioning

A collection of examples demonstrating various valid formats for API version numbers in Swagger Studio, including pre-release tags and build metadata.

```text
1
1.0
0.0.1
1.2.3.4
2.4_15
1.0b5
1.2.0-rc3
v1
beta
2016-04-15
2.0.0-SNAPSHOT+20211116
```

--------------------------------

### Example Parameter Value for Interactive Docs (OpenAPI 2.0)

Source: https://support.smartbear.com/swagger/studio/docs/en/manage-apis/swaggerhub-vendor-extensions

The 'x-example' vendor extension is used to specify example values for parameters in OpenAPI 2.0. These examples populate the 'try it out' form in interactive API documentation, enhancing usability.

```yaml
parameters:
  - in: query
    name: q
    type: string
    description: Search string
    x-example: swagger    # <-------
```

--------------------------------

### Generate cURL Command Examples (Bash)

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Interactive API documentation can generate cURL command examples for Bash. This is useful for testing API endpoints directly from the command line.

```bash
# Example: This is a placeholder for a generated cURL command.
```

--------------------------------

### AsyncAPI Domain Definition

Source: https://support.smartbear.com/swagger/studio/docs/en/domains/asyncapi-domain-example

This section provides an example of an AsyncAPI domain definition. It includes information about the API, channels, components like messages, schemas, parameters, and message traits.

```APIDOC
## AsyncAPI Domain Example

### Description
This example demonstrates an AsyncAPI domain definition, illustrating various domain components.

### Method
N/A (This is a definition, not an endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Response
N/A

## Components

### Messages
#### exampleMessage
- **name**: `exampleMessage` (string)
- **title**: `Example message` (string)
- **summary**: `A message that shows a nice example.` (string)
- **contentType**: `application/json` (string)
- **traits**: `$ref: '#/components/messageTraits/commonHeaders'`
- **payload**: `$ref: "#/components/schemas/exampleMessageSchema"`

### Schemas
#### exampleMessageSchema
- **type**: `object`
- **properties**:
  - **text**: `string` - An example message.
  - **sentAt**: `$ref: "#/components/schemas/sentAt"`

#### sentAt
- **type**: `string`
- **format**: `date-time`
- **description**: `Date and time when the message was sent.`

### Parameters
#### parameterId
- **description**: `The ID of the parameter.` (string)
- **schema**: `type: string`

### Message Traits
#### commonHeaders
- **headers**:
  - **type**: `object`
  - **properties**:
    - **my-app-header**: `integer` - Minimum: 0, Maximum: 100
```

--------------------------------

### OpenAPI 3.0: Sample API Definition with a GET Endpoint

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

Illustrates a simple OpenAPI 3.0 definition that includes meta-information and defines a basic '/artists' endpoint with a GET operation. This shows how to specify available API paths and the HTTP methods they support.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple API
  description: A simple API to illustrate OpenAPI concepts

servers:
  - url: https://example.io/v1

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []

#  ----- Added lines  ----------------------------------------
paths:
  /artists:
    get:
     description: Returns a list of artists 
#  ---- /Added lines  ----------------------------------------
```

--------------------------------

### Generate cURL Command Examples (PowerShell)

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Interactive API documentation can generate cURL command examples for PowerShell. This allows users to test API endpoints in a Windows environment.

```powershell
# Example: This is a placeholder for a generated cURL command in PowerShell.
```

--------------------------------

### Generate cURL Command Examples (Windows CMD)

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Interactive API documentation can generate cURL command examples for Windows Command Prompt (CMD). This facilitates API testing on Windows systems.

```cmd
REM Example: This is a placeholder for a generated cURL command in CMD.
```

--------------------------------

### Manually Add Examples for oneOf/anyOf Schemas in OpenAPI 3.0

Source: https://support.smartbear.com/swagger/studio/docs/en/openapi-3-0-support

When interactive documentation does not automatically generate examples for 'oneOf' and 'anyOf' schemas in OpenAPI 3.0, you can manually add them. This involves providing an 'example' key with a sample JSON object that conforms to one of the specified schemas.

```yaml
oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
example:
  petType: dog
  name: Rex
```

--------------------------------

### Domain Referencing Syntax Examples

Source: https://support.smartbear.com/swagger/studio/docs/en/domains

Provides examples of how to reference domain components within API definitions using absolute '$ref' links. Different syntaxes are shown for OpenAPI 2.0, OpenAPI 3.0, and AsyncAPI 2.x.

```yaml
# OpenAPI 2.0
$ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/TYPE/COMPONENT_NAME
```

```yaml
# OpenAPI 3.0
$ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME
```

```yaml
# AsyncAPI 2.x
$ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME
```

--------------------------------

### AsyncAPI Domain Definition Example (YAML)

Source: https://support.smartbear.com/swagger/studio/docs/en/domains/asyncapi-domain-example

This YAML snippet defines an AsyncAPI domain, including information about the API, channels, and reusable components. It showcases message definitions with payloads and traits, schema definitions, parameter definitions, and message trait definitions.

```yaml
asyncapi: '2.4.0'

info:
  title: AsyncAPI Domain
  version: '1.0.0'
  description: An example domain for AsyncAPI

channels: {}
components:
  messages:
    exampleMessage:
      name: exampleMessage
      title: Example message
      summary: A message that shows a nice example.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        $ref: "#/components/schemas/exampleMessageSchema"

  schemas:
    exampleMessageSchema:
      type: object
      properties:
        text:
          type: string
          description: An example message.
        sentAt:
          $ref: "#/components/schemas/sentAt"

    sentAt:
      type: string
      format: date-time
      description: Date and time when the message was sent.

  parameters:
    parameterId:
      description: The ID of the parameter.
      schema:
        type: string

  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          my-app-header:
            type: integer
            minimum: 0
            maximum: 100

```

--------------------------------

### Basic Swagger 2.0 Definition

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

A minimal Swagger 2.0 definition in YAML format, showcasing the basic structure including swagger version, API info, and a sample path.

```yaml
swagger: '2.0'
info:
  version: 1.0.0
  title: Simple example API
  description: An API to illustrate Swagger
paths:
  /list:
    get:
      description: Returns a list of stuff              
      responses:
        200:
          description: Successful response 

```

--------------------------------

### Valid Version Characters

Source: https://support.smartbear.com/swagger/studio/docs/en/manage-apis/versioning

This example lists the allowed characters for API version numbers in Swagger Studio. It includes alphanumeric characters, periods, underscores, hyphens, and plus signs. Note that '+' is specific to Swagger Studio SaaS.

```text
0-9 A-Z a-z . _ - +
```

--------------------------------

### OpenAPI/AsyncAPI Domain Info Section Example

Source: https://support.smartbear.com/swagger/studio/docs/en/domains

Demonstrates the 'info' section for a domain, which is optional but can include title, description, terms of service, contact information, license, and version. This information is displayed in interactive documentation and 'My APIs'.

```yaml
info:
  title: Components
  description: Common components for Acme REST APIs.
  termsOfService: http://example.com/exampleterms/
  contact:
    name: Core team
    url: http://www.example.com/coreteam
    email: apiteam@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.1
```

--------------------------------

### Protect GET/HEAD Operations with Security Schemes (OpenAPI)

Source: https://support.smartbear.com/swagger/studio/docs/en/manage-resource-access/api-governance/owasp-top-10

Ensures that GET and HEAD operations are protected by a security scheme, either globally or at the operation level. This is vital for securing API endpoints as per OWASP API2:2019. The example shows a valid operation-level security configuration.

```yaml
paths:
  '/users/{userId}':
    get:
      ...
      responses:
        ...
      security:
        - API Key: []
```

--------------------------------

### Help Menu Simplification

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

The help menu has been simplified, and a 'Give Feedback' link has been added for users to participate in UX research.

```APIDOC
## Help Menu Simplification

### Description
Streamlines the user interface by simplifying the help menu. Additionally, a 'Give Feedback' link is introduced, allowing logged-in users to easily sign up for Swagger Studio UX research opportunities.

### Method
N/A (UI enhancement)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **Help Menu**: Simplified layout.
- **Give Feedback Link**: Added to the help menu for UX research sign-ups.
```

--------------------------------

### Response Mocking: JSON Body Example (OpenAPI 3.0)

Source: https://support.smartbear.com/swagger/studio/docs/en/integrations/api-auto-mocking

Shows how mock responses select an example from a list of defined `examples` for `application/json` in OpenAPI 3.0. The first non-`externalValue` example is used if multiple are present.

```yaml
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          type: object
        examples:
          cat:
            summary: An example of a cat
            value:
              name: Moon
              petType: cat
              color: gray
              gender: female
          dog:
            summary: An example of a dog
            value:
              name: Gromit
              petType: dog
              color: white
              gender: male
```

--------------------------------

### Include Examples for Model Properties (OpenAPI)

Source: https://support.smartbear.com/swagger/studio/docs/en/manage-resource-access/api-governance

Examples for model properties in the `definitions` section are vital for generating sample requests/responses and mock data. Meaningful examples aid consumers in understanding data formats. For array properties, an array-level example is required.

```yaml
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
        example: 1
      username:
        type: string
        example: demo-user
```

```yaml
# Good array example
definitions:
  Product:
    type: object
    properties:
      categories:
        type: array
        items:
          type: string
        example:
          - clothes
          - accessories
```

```yaml
# Bad array example (item example not sufficient)
definitions:
  Product:
    type: object
    properties:
      categories:
        type: array
        items:
          type: string
          example: clothes
```

--------------------------------

### POST /artists

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

Creates a new artist in the database.

```APIDOC
## POST /artists

### Description
Lets a user post a new artist.

### Method
POST

### Endpoint
/v1/artists

### Parameters
#### Request Body
- **artist** (object) - Required - Creates a new artist in our database
  - **artist_name** (string) - Optional - The name of the artist.
  - **artist_genre** (string) - Optional - The genre of the artist.
  - **albums_recorded** (integer) - Optional - The number of albums recorded by the artist.
  - **username** (string) - Required - The unique username of the artist.

### Request Example
```json
{
  "artist_name": "New Artist",
  "artist_genre": "Pop",
  "albums_recorded": 2,
  "username": "new_artist_123"
}
```
### Response
#### Success Response (200)
Successfully created a new artist.

#### Error Response (400)
- **message** (string) - Description of the error.

#### Error Response Example
```json
{
  "message": "Invalid request"
}
```
```

--------------------------------

### OpenAPI: Define Query Parameters for API

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

This OpenAPI 3.0 snippet defines 'limit' and 'offset' as query parameters for the /artists GET endpoint. 'limit' controls the number of items returned per page, and 'offset' specifies the page number. These parameters are defined with integer types and descriptions to guide API consumers.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple API
  description: A simple API to illustrate OpenAPI concepts

servers:
  - url: https://example.io/v1

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []

paths:
  /artists:
    get:
      description: Returns a list of artists 
      parameters:
        - name: limit
          in: query
          description: Limits the number of items on a page
          schema:
            type: integer
        - name: offset
          in: query
          description: Specifies the page number of the artists to be displayed
          schema:
            type: integer
      responses:
        '200':
          description: Successfully returned a list of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - username
                  properties:
                    artist_name:
                      type: string
                    artist_genre:
                      type: string
                    albums_recorded:
                      type: integer
                    username:
                      type: string

        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:   
                  message:
                    type: string
```

--------------------------------

### Response Mocking: JSON Body Example (OpenAPI 2.0)

Source: https://support.smartbear.com/swagger/studio/docs/en/integrations/api-auto-mocking

Illustrates how mock responses utilize defined `examples` for `application/json` in OpenAPI 2.0. If `schema` is present but `examples` are not, it falls back to schema-based generation.

```yaml
produces:
  - application/json
responses:
  200:
    description: OK
    schema:
      type: object
    examples:
      application/json:
        id: 42
        name: Arthur Dent
```

--------------------------------

### POST /artists

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

Creates a new artist in the database.

```APIDOC
## POST /artists

### Description
Lets a user post a new artist to the database.

### Method
POST

### Endpoint
/v1/artists

### Parameters
#### Request Body
- **artist** (object) - Required - An object containing the details of the artist to be created.
  - **artist_name** (string) - The name of the artist.
  - **artist_genre** (string) - The genre of the artist.
  - **albums_recorded** (integer) - The number of albums recorded by the artist.
  - **username** (string) - The unique username of the artist.

### Request Example
```json
{
  "artist_name": "New Artist",
  "artist_genre": "Pop",
  "albums_recorded": 1,
  "username": "new_artist_1"
}
```

### Response
#### Success Response (200)
Description: Successfully created a new artist.

#### Error Response (400)
- **message** (string) - Description of the error.

#### Response Example (400)
```json
{
  "message": "Invalid request"
}
```
```

--------------------------------

### POST /artists

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

Creates a new artist in the database.

```APIDOC
## POST /artists

### Description
Lets a user post a new artist. The request body must contain the artist's details.

### Method
POST

### Endpoint
/v1/artists

### Parameters
#### Request Body
- **artist** (Artist) - Required - The details of the artist to be created.

### Request Example
{
  "example": "{
    \"username\": \"janedoe\",
    \"artist_name\": \"Jane Doe\",
    \"artist_genre\": \"Pop\",
    \"albums_recorded\": 3
  }"
}

### Response
#### Success Response (200)
- The response indicates successful creation. Specific details may vary.

#### Response Example
{
  "example": "{
    \"message\": \"Artist created successfully\" 
  }"
}

#### Error Response (400)
- **message** (string) - Description of the error.

#### Response Example
{
  "example": "{
    \"message\": \"Invalid request body, missing required fields\"
  }"
}
```

--------------------------------

### OpenAPI 3.0: Minimal API Definition with a List Endpoint

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

Provides a very basic OpenAPI 3.0 specification demonstrating the 'openapi', 'info', and 'paths' sections. It defines a single endpoint '/list' with a GET operation and a success response, suitable for illustrating fundamental structure.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts
paths:
  /list:
    get:
      description: Returns a list of stuff              
      responses:
        '200':
          description: Successful response
```

--------------------------------

### Define API Path Item and GET Method in Swagger

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

This snippet demonstrates how to define an API path item, specifically '/artists', and associate a GET HTTP method with it. It includes basic OpenAPI 2.0 structure with host, basePath, and security definitions. The GET method is described as returning a list of artists.

```yaml
swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
  description: A simple API to understand the Swagger Specification in greater detail

schemes: 
- https
host: example.io
basePath: /v1

securityDefinitions:
  UserSecurity:
    type: basic

security:
  - UserSecurity: [] 

#  ----- Added lines  ----------------------------------------
paths:
  /artists:
    get:
     description: Returns a list of artists 
#  ---- /Added lines  ----------------------------------------
```

--------------------------------

### Get Organizations for a User via API (cURL)

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Retrieves a list of organizations associated with a user using the GET /user-management/v1/orgs endpoint. Requires an API key for authentication.

```curl
curl https://api.swaggerhub.com/user-management/v1/orgs -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### GET /user-management/v1/orgs/{OWNERID}/roles

Source: https://support.smartbear.com/swagger/studio/docs/en/swaggerhub-apis/user-management-api

Get all roles assigned to a user in the organization. You can display a list of all roles assigned to a user in different resources in the organization.

```APIDOC
## GET /user-management/v1/orgs/{OWNERID}/roles

### Description
Get all roles assigned to a user in the organization. You can display a list of all roles assigned to a user in different resources in the organization.

### Method
GET

### Endpoint
`https://api.swaggerhub.com/user-management/v1/orgs/{OWNERID}/roles`

### Parameters
#### Path Parameters
- **OWNERID** (string) - Required - The ID of the organization owner.

#### Query Parameters
- **user** (string) - Required - The email address of the user.
- **page** (integer) - Optional - The page number for pagination (default: 0).
- **pageSize** (integer) - Optional - The number of items per page (default: 50).

### Request Example
```
https://api.swaggerhub.com/user-management/v1/orgs/OWNERID/roles?user=user%40example.com&page=0&pageSize=50
```

### Response
#### Success Response (200)
- **roles** (array) - A list of roles assigned to the user.
  - **resourceType** (string) - The type of resource.
  - **resourceName** (string) - The name of the resource.
  - **role** (string) - The role assigned.
```

--------------------------------

### OpenAPI 3.0 Domain Definition Example

Source: https://support.smartbear.com/swagger/studio/docs/en/domains/openapi-3-0-domain-example

This code snippet is an OpenAPI 3.0 domain definition. It illustrates the structure and various components of an OpenAPI definition, including versioning, info section, reusable components like schemas, parameters, request bodies, responses, headers, path items, and examples. This definition can be used to describe RESTful APIs.

```yaml
# OpenAPI version identifier - required for OpenAPI 3.0 domains
openapi: 3.0.0

#######################
# Optional info section
#######################
info:
  title: Acme Components
  description: Common components for Acme REST APIs
  version: 1.0.0

components:

  ####################
  # Common data models
  ####################
  schemas:
    ErrorModel:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

  ####################
  # Common parameters
  ####################
  parameters:
    offsetParam:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
      description: The number of items to skip before returning the results
    limitParam:
      in: query
      name: limit
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
      description: The number of items to return

  #######################
  # Common request bodies
  #######################
  requestBodies:
    NewItem:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            type: object
          examples:
            tshirt:
              $ref: '#/components/examples/tshirt'

  ####################
  # Common responses
  ####################
  responses:
    GeneralError:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'

  #########################
  # Common headers
  # (except request headers - they are defined as parameters)
  #########################
  headers:
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
      example: 100
    X-RateLimit-Remaining:
      description: Remaining requests for the hour
      schema:
        type: integer
      example: 94

  #######################
  # Common path items
  #######################
  pathitems:
    EntityOperations:
      get:
        summary: Get all items
        description: This operation supports pagination
        parameters:
          - $ref: '#/components/parameters/offsetParam'
          - $ref: '#/components/parameters/limitParam'
        responses:
          '200':
            description: A list of items
            headers:
              X-RateLimit-Limit:
                $ref: '#/components/headers/X-RateLimit-Limit'
              X-RateLimit-Remaining:
                $ref: '#/components/headers/X-RateLimit-Remaining'
          default:
            $ref: '#/components/responses/GeneralError'
      post:
        summary: Add a new item
        requestBody:
          $ref: '#/components/requestBodies/NewItem'
        responses:
          '201':
            description: Created
            headers:
              X-RateLimit-Limit:
                $ref: '#/components/headers/X-RateLimit-Limit'
              X-RateLimit-Remaining:
                $ref: '#/components/headers/X-RateLimit-Remaining'

  ######################################
  # Common examples of input/output data
  ######################################
  examples:
    tshirt:
      summary: Sample T-shirt data
      value:
        # Example value starts here
        id: 17
        name: T-shirt
        description: 100% cotton shirt
        categories: [clothes]

  #########################
  # Common link definitions
  # See: https://swagger.io/docs/specification/links/
  #########################
  links: {}
  
  #########################
  # Common callback definitions
  # See: https://swagger.io/docs/specification/callbacks/
  #########################
  callbacks: {}

```

--------------------------------

### Proxy Server Address Examples

Source: https://support.smartbear.com/swagger/studio/docs/en/integrations/amazon-api-gateway-integration

Provides examples of correct and incorrect formats for the 'Address of the Server to Proxy to' field when configuring an Amazon API Gateway integration. This is the back-end endpoint API Gateway will proxy requests to.

```text
Correct:
```
http://api.example.com/reports/v2
https://myapi.com
```

Incorrect:
```
https://myapi.com/
```
```

--------------------------------

### Swagger 2.0 Meta Information with Security

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-2-0-tutorial

A Swagger 2.0 definition including meta information such as API version, title, description, host, base path, and basic authentication settings.

```yaml
swagger: '2.0'
info:
  version: 1.0.0
  title: Simple Artist API
  description: A simple API to understand the Swagger Specification in greater detail

schemes:
- https
host: example.io
basePath: /v1

securityDefinitions:
  UserSecurity:
    type: basic

security:
  - UserSecurity: []

paths: {}

```

--------------------------------

### GET /user-management/v1/orgs/{OWNERID}/resources/{RESOURCENAME}/resource-type/API/teams

Source: https://support.smartbear.com/swagger/studio/docs/en/swaggerhub-apis/user-management-api

Get teams with access control assigned on the resource. You can display a list of teams with access to a specified resource.

```APIDOC
## GET /user-management/v1/orgs/{OWNERID}/resources/{RESOURCENAME}/resource-type/API/teams

### Description
Get teams with access control assigned on the resource. You can display a list of teams with access to a specified resource.

### Method
GET

### Endpoint
`https://api.swaggerhub.com/user-management/v1/orgs/{OWNERID}/resources/{RESOURCENAME}/resource-type/API/teams`

### Parameters
#### Path Parameters
- **OWNERID** (string) - Required - The ID of the organization owner.
- **RESOURCENAME** (string) - Required - The name of the resource.

#### Query Parameters
- **page** (integer) - Optional - The page number for pagination (default: 0).
- **pageSize** (integer) - Optional - The number of items per page (default: 50).

### Request Example
```
https://api.swaggerhub.com/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/teams?page=0&pageSize=50
```

### Response
#### Success Response (200)
- **teams** (array) - A list of teams with access control assigned to the resource.
  - **name** (string) - The name of the team.
  - **role** (string) - The role assigned to the team members.
```

--------------------------------

### POST /artists

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

Creates a new artist entry in the system.

```APIDOC
## POST /artists

### Description
Lets a user post a new artist.

### Method
POST

### Endpoint
/artists

### Parameters
#### Request Body
- **artist_name** (string) - Optional - The name of the artist.
- **artist_genre** (string) - Optional - The genre of the artist.
- **albums_recorded** (integer) - Optional - The number of albums recorded by the artist.
- **username** (string) - Required - The unique username of the artist.

### Request Example
```json
{
  "artist_name": "New Artist",
  "artist_genre": "Pop",
  "albums_recorded": 1,
  "username": "new_artist_123"
}
```

### Response
#### Success Response (200)
- (No specific fields described for success response)

#### Error Response (400)
- **message** (string) - Description of the error.

#### Error Response Example
```json
{
  "message": "Invalid request body"
}
```
```

--------------------------------

### Registry API: Get API Standardization Errors (GET)

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Retrieves validation or standardization errors for a specific API version. The operation requires owner, API name, and version in the path.

```http
GET /apis/{owner}/{api}/{version}/validation
```

--------------------------------

### Registry API: Get All Projects

Source: https://support.smartbear.com/swagger/studio/docs/en/what-s-new

Retrieves a list of all projects to which the authenticated user has access.

```APIDOC
## GET /projects

### Description
Retrieves a list of all projects to which a user has access.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
  - **id** (string) - The unique identifier of the project.
  - **name** (string) - The name of the project.

#### Response Example
```json
{
  "projects": [
    {
      "id": "project-123",
      "name": "My Project"
    }
  ]
}
```
```

--------------------------------

### OpenAPI 3.0: Reusable Parameters and Responses

Source: https://support.smartbear.com/swagger/studio/docs/en/get-started/openapi-3-0-tutorial

Defines reusable query parameters 'PageLimit' and 'PageOffset', and a '400Error' response within the 'components' section. These are then referenced in the '/artists' and '/artists/{username}' paths to structure API requests and responses efficiently.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Simple API
  description: A simple API to illustrate OpenAPI concepts

servers:
  - url: https://example.io/v1

security:
  - BasicAuth: []

paths:
  /artists:
    get:
      description: Returns a list of artists 
      parameters:
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: Successfully returned a list of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Artist'
        '400':
          $ref: '#/components/responses/400Error'

    post:
      description: Lets a user post a new artist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Artist'
      responses:
        '200':
          description: Successfully created a new artist
        '400':
          $ref: '#/components/responses/400Error'    

  /artists/{username}:
    get:
      description: Obtain information about an artist from his or her unique username
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          
      responses:
        '200':
          description: Successfully returned an artist
          content:
            application/json:
              schema:
                type: object
                properties:
                  artist_name:
                    type: string
                  artist_genre:
                    type: string
                  albums_recorded:
                    type: integer
                
        '400':
          $ref: '#/components/responses/400Error'     

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

  schemas:
    Artist:
      type: object
      required:
        - username
      properties:
        artist_name:
          type: string
        artist_genre:
            type: string
        albums_recorded:
            type: integer
        username:
            type: string

  parameters:
    PageLimit:
      name: limit
      in: query
      description: Limits the number of items on a page
      schema:
        type: integer
      
    PageOffset:
      name: offset
      in: query
      description: Specifies the page number of the artists to be displayed
      schema:
        type: integer

  responses:
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object 
            properties:
              message:
                type: string

```

--------------------------------

### GET /user-management/v1/orgs/{OWNERID}/resource-types

Source: https://support.smartbear.com/swagger/studio/docs/en/swaggerhub-apis/user-management-api

Get all resource types and roles that can be assigned. You can display a list of all resource types and the roles you can assign to organization members for each type of resource.

```APIDOC
## GET /user-management/v1/orgs/{OWNERID}/resource-types

### Description
Get all resource types and roles that can be assigned. You can display a list of all resource types and the roles you can assign to organization members for each type of resource.

### Method
GET

### Endpoint
`https://api.swaggerhub.com/user-management/v1/orgs/{OWNERID}/resource-types`

### Parameters
#### Path Parameters
- **OWNERID** (string) - Required - The ID of the organization owner.

#### Query Parameters
None

### Request Example
```
https://api.swaggerhub.com/user-management/v1/orgs/OWNERID/resource-types
```

### Response
#### Success Response (200)
- **resourceTypes** (array) - A list of available resource types and their assignable roles.
  - **resourceType** (string) - The name of the resource type.
  - **roles** (array) - A list of roles that can be assigned for this resource type.
    - **name** (string) - The name of the role.
```
Tokens:
Raw