Using REST API Descriptors for Your REST Application
A REST API descriptor provides a way of describing the operations provided by one or more REST resources together with information about how to access those operations, the MIME types the resources consume and produce, and the expected input and output for the operations. Fundamentally, a REST API descriptor is composed of REST resources and information about how to access those resources. Using this information, Integration Server creates and maintains a Swagger document for the REST API descriptor. Integration Server generates the Swagger document based on version 2.0 of the Swagger specification.
Note: You can create REST API descriptors using the legacy approach to expose the legacy REST APIs as Swagger document.
Using Designer you can create a REST API descriptor using resource first or Swagger first approach.
Resource first refers to REST API descriptors created using the REST v2 resource. For more information about creating a REST API descriptor using the resource first approach, refer to the
webMethods Service Development Help.
Note: The base path of the created REST API descriptor is set as /rad/<namespaceName of the REST API descriptor> or path in the Swagger document. You can change the base path. To avoid exposing the server namespace name to the end user, set the base path to an application specific path. Also, when you change the base path, you must create a URL alias with the defined base path. For more information about creating a URL alias, refer to the webMethods Service Development Help.
Swagger first refers to REST API descriptors created by importing a Swagger document. During this process,
Integration Server creates services, doctypes, and RESTv2 resources based on the contents of the Swagger document. The application developer then provides the service implementation of the generated services. You can then invoke the REST application through a client. Because the Swagger specification does not include resource definitions,
Integration Server allows you to create the REST V2 resources based on tags or based on the Swagger paths. Tags defined in a Swagger document are used for grouping of operations. If you choose to create a REST V2 resource based on tags, all the operations associated to a tag are grouped together. Otherwise, the resources are created based on the Swagger path. For more information about creating a REST API descriptor using a Swagger document, refer to the
webMethods Service Development Help.
Note: In the Swagger first approach to create a REST API descriptor, Integration Server automatically creates a URL alias for the base path of the created REST API descriptor.