Expert view

The Expert view displays the auto-generated OpenAPI 3 specification containing all of the components of the API Namespace, and it's a preview of how the generated specs will look like when committing the project to the git repository. The Expert view is accessed through the Expert view tab in the API Namespace.

Note:

For the deployed service, some additional data will be added to the API specification, e. g. the service url and security configuration.

Inspecting the API specification in the Expert view

Default parameters

When opening the Expert view, you can see that there are some parameters added to the API specification by default. Even though those parameters are not visible in the Solution Designer UI, they are applied automatically in any API operations.

Default parameters used in API operations:

paths:
  /pets:
    get:
      tags: []
      operationId: getPets
      parameters:
        - $ref: '#/components/parameters/Accept-Language'
        - $ref: '#/components/parameters/X-B3-ParentSpanId'
        - $ref: '#/components/parameters/X-B3-SpanId'
        - $ref: '#/components/parameters/X-B3-TraceId'
        - $ref: '#/components/parameters/X-B3-Sampled'
        - $ref: '#/components/parameters/X-DEBUG-SESSION'

Specific constants

At the bottom of the Expert view, there will be some constants that shouldn't be edited or removed as these are used internally by the Solution Designer. The values of these x-knowis constants will not change even if it is edited or removed.

x-knowis-solutionAcronym: TSLOWCODEAPI
x-knowis-apiName: pet
x-knowis-namespacePrefix: pet
x-knowis-ibmBpmIntegration: false
x-knowis-ibmApiConnectIntegration: false
x-knowis-language: typescript
x-knowis-supportedspec: openApi3.0

Editing the API Namespace through the Expert view

The API Namespace components can be edited in the Expert view by clicking the Edit API specification button.

Note:

By editing the API specification through the Expert view, the whole namespace will be adjusted automatically.

Warning:

Be aware of a possible loss of documentation by using the Expert view. Please note that if you change the API specification via the expert mode, any existing documentation of the spec artifacts is discarded. Either use the modeling capabilities or make sure that you can preserve the documentation beforehand and apply it later again.

If you want to apply OpenApi 3 features to your REST API, which are not supported through the modelling capabilities in the Solution Designer UI, you can also use the editor in the Expert view to add those.

Note:

Even though not all features are supported in the UI, the API of the deployed service will try to apply all valid OpenAPI 3 features correctly. Please find the list of API validations below.

API validations

  • General validations:
    • no duplicated items (is valid in OpenApi 3.0/Swagger 2.0 with lower- and upper-cased)
    • valid Contact E-mail
    • valid Contact URL
    • valid License URL
    • valid Terms of Service URL
  • Paths:
    • must meet the general validation rules for paths
  • Operations:
    • must meet the general validation rules for operations
    • only POST, GET, PUT and DELETE operations are directly supported by the Solution Designer, while PATCH, HEAD, OPTIONS, TRACE operations are only accessible through the Expert view.
    • operations GET and DELETE are not supported to have a request body
    • inline and referenced parameters are supported
    • inline and referenced request bodies are supported
    • inline and referenced responses are supported
    • only one request body is supported per operation
    • no duplicated status codes are allowed in responses
  • Parameters:
    • must meet the general validation rules for parameters
    • for referenced parameters, schemas of type string, boolean, integer and number are allowed. For inline parameters primitive inline schemas are supported as well
    • Parameters with generic object or array schemas are only accessible through the Expert view
    • Parameter location can be either Path, Query or Header Note: header parameters named Accept, Content-Type and Authorization are not allowed.
    • Parameters in cookie are only supported through the Expert view
  • Request Bodies:
    • must meet the general validation rules for request bodies
    • only referenced Object and Array schemas are supported by the Solution Designer
    • other schema types, and inline schemas are only accessible through the Expert view
  • Responses:
    • must meet the general validation rules for responses
    • only referenced Object and Array schemas are supported by the Solution Designer
    • other schema types, and inline schemas are only accessible through the Expert view
    • application/json and application/json; charset=utf-8 are supported by Solution Designer, other content types are only accessible through the Expert view
  • Schemas:
    • must meet the general validation rules for schemas
    • Solution Designer supports only referenced schemas as array items
    • Solution Designer supports only referenced object schemas as AllOf schemas
    • Solution Designer does not support inline object schemas as schema properties
    • Solution Designer supports only referenced object schemas as OneOf schemas and discriminator is required here
    • All of the other compliant OpenAPI 3 features are only accessible through the Expert view

In case that the API Namespace contains any OpenAPI 3 feature which is not supported by the Solution Designer UI, the Expert view will show detailed information about the unsupported OpenAPI 3 features.