robinbuschmann/soap-typescript

SOAP decorators for creating wsdl's and annotating services to provide metadata for node-soap

soap-decorators

SOAP decorators for creating wsdl's and annotating services to provide metadata for node-soap.

Installation

npm install soap-decorators --save

Usage

Input and output messages

Define input and output message interfaces for a soap service.

import {XSDComplexType, XSDElement} from 'soap-decorators';

@XSDComplexType
export class CalculatorInput {

  @XSDElement
  a: number;

  @XSDElement
  b: number;
}

@XSDComplexType
export class CalculatorResult {

  @XSDElement
  value: number;
}

For a more advanced usage of creating xsd schemas with decorators see xsd-decorators.

Soap service and operations

Define soap service, its operations and specify input and output messages via the previously defined classes.

import {SoapService, SoapOperation} from 'soap-decorators';

@SoapService({
  portName: 'CalculatorPort',
  serviceName: 'CalculatorService'
})
export class CalculatorController {

  @SoapOperation(CalculatorResult)
  add(data: CalculatorInput) {

    return {
      value: data.a + data.b
    };
  }

  @SoapOperation(CalculatorResult)
  subtract(data: CalculatorInput) {

    return Promise.resolve({
      value: data.a - data.b
    });
  }
}

Use soap service with express.js

soap-decorators provides a middleware for express, which does all the magic for you. The wsdl will be resolved and the location address and tns will be set automatically.

import {soap} from 'soap-decorators';

const app = express();
const calculatorController = new CalculatorController();

// resolves wsdl for you and sets location address and tns to current requested url
app.use('/soap/calculation', soap(calculatorController));

Requesting WSDL

Now you can ask for the wsdl by requesting against the defined endpoint.

GET /soap/calculation?wsdl

Response

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' 
                  xmlns:xsd='http://www.w3.org/2001/XMLSchema' 
                  xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' 
                  name='CalculatorService' 
                  targetNamespace='https://calculation.example.com'
                  xmlns:tns='https://calculation.example.com'>
    <wsdl:types>
        <xsd:schema attributeFormDefault='unqualified' elementFormDefault='unqualified' xmlns:xsd='http://www.w3.org/2001/XMLSchema' targetNamespace='https://calculation.example.com'>
            <xsd:element name='add' type='tns:CalculatorInput'/>
            <xsd:element name='CalculatorResult' type='tns:CalculatorResult'/>
            <xsd:element name='subtract' type='tns:CalculatorInput'/>
            <xsd:complexType name='CalculatorInput'>
                <xsd:sequence>
                    <xsd:element name='a' type='xsd:int'/>
                    <xsd:element name='b' type='xsd:int'/>
                </xsd:sequence>
            </xsd:complexType>
            <xsd:complexType name='CalculatorResult'>
                <xsd:sequence>
                    <xsd:element name='value' type='xsd:int'/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name='addMessage'>
        <wsdl:part name='add' element='tns:add'/>
    </wsdl:message>
    <wsdl:message name='CalculatorResultMessage'>
        <wsdl:part name='CalculatorResult' element='tns:CalculatorResult'/>
    </wsdl:message>
    <wsdl:message name='subtractMessage'>
        <wsdl:part name='subtract' element='tns:subtract'/>
    </wsdl:message>
    <wsdl:portType name='CalculatorPortType'>
        <wsdl:operation name='add'>
            <wsdl:input message='tns:addMessage'/>
            <wsdl:output message='tns:CalculatorResultMessage'/>
        </wsdl:operation>
        <wsdl:operation name='subtract'>
            <wsdl:input message='tns:subtractMessage'/>
            <wsdl:output message='tns:CalculatorResultMessage'/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name='CalculatorServiceBinding' type='tns:CalculatorPortType'>
        <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/>
        <wsdl:operation name='add'>
            <wsdl:input>
                <soap:body use='literal' parts='add'/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use='literal' parts='CalculatorResult'/>
            </wsdl:output>
            <soap:operation soapAction='add'/>
        </wsdl:operation>
        <wsdl:operation name='subtract'>
            <wsdl:input>
                <soap:body use='literal' parts='subtract'/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use='literal' parts='CalculatorResult'/>
            </wsdl:output>
            <soap:operation soapAction='subtract'/>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name='CalculatorService'>
        <wsdl:port name='CalculatorPort' binding='tns:CalculatorServiceBinding'>
            <soap:address location='https://calculation.example.com/soap/v1'/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Using operations

POST /soap/calculation

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="https://calculation.example.com">
   <soapenv:Header/>
   <soapenv:Body>
      <cal:add>
         <a>3</a>
         <b>1</b>
      </cal:add>
   </soapenv:Body>
</soapenv:Envelope>

POST /soap/calculation

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="https://calculation.example.com">
   <soapenv:Header/>
   <soapenv:Body>
      <cal:subtract>
         <a>8</a>
         <b>4</b>
      </cal:subtract>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://localhost:3000/calculation">
   <soap:Body>
      <CalculatorResult>
         <value>4</value>
      </CalculatorResult>
   </soap:Body>
</soap:Envelope>

Retrieving WSDL from class or instance

import {createWsdl} from 'soap-decorators';

const instance = new CalculatorController();

createWsdl(instance) === createWsdl(CalculatorController);

soap-typescript's Issues

Create package.json file for example

package.json could have dependencies for example & tsc compile & run instructions

Support for multiple namespaces?

Hallo,
do you also support WSDL requests with mixed namespaces? For example:

<BankData> <cis:accountOwner>Max Mustermann</cis:accountOwner> ... </BankData>

Using as a client

How one can use this as a client to SOAP service? I guess annotated classes populated with data can be used to make properly formatted SOAP requests as well.

Thanks.

Using soap-typescript

Hi Robin/ anyone,

I am new to node.js and I want to create a wsdl file for my node-soap or strong-soap service (on server). I know this question does not belong here but I have been looking for detailed examples of your soap-typescript package on the web with no luck. So what I did is I pasted the first three code snippets as per the readme in https://www.npmjs.com/package/soap-decorators, onto one file called createWsdl.js and then I ran "node createWsdl.js" and I get error: Unexpected token import. I also tried to run <GET /soap/calculation?wsdl> from linux shell command line. It seems to run fine but I am not convinced it picked up the code in createWsdl.js and I also don't know where its output is written/logged. Could you please point me to a detailed example.
Sorry for posting this question here, and sorry for asking you to spoon feed me; as I said I am new to node.js. Thank you.

I have posted a question on stack overflow in case you want to answer there: https://stackoverflow.com/questions/50962718/robinbuschmann-soap-typescript-soap-decorators-example

Support for authentication ?

What's possible in terms of authentication of SOAP requests with the middleware you provide ?

Change name atribuite

Hello, first of all, congratulation for the lib.
I have a doubt, how i can change the key that is used in wsdl definition element name inside <xsd:complexType >...<xsd:complexType?

For exemple in image bellow:

My goal is to change the value of this data

Sorry my English.

Support SOAP fault element?

Hello, do you also support throwing SOAP fault like in node-soap: https://github.com/vpulim/node-soap#soap-fault ?

Not specifying a targetNamespace in the SoapService options prevents use with .NET 2.0 Web Services

This is due to the "tns" attribute of the response envelope being set to a "{{CURRENT_URL}}" placeholder, which clearly doesn't get macro'd to the current url, which would be a suitable default for a .NET 2.0 consumer.

To prevent this issue, in your service definition, make sure the options you specify to @SoapService contain the field targetNamespace, set to the current URL for instance.