[teiid-issues] [JBoss JIRA] (TEIID-3520) Extend the Swagger support in the WS Translator

[Ramesh Reddy (JIRA)]

    [ https://issues.jboss.org/browse/TEIID-3520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13117579#comment-13117579 ] 

Ramesh Reddy commented on TEIID-3520:
-------------------------------------

[~kylin] I had to reject the pull request, as every time I spend few more minutes I learn more about the Swagger Specification than before ;)

Swagger is complete definition of Rest Service API, 
 - It has data type definitions. It defines all primitive data types
 - It has Model definitions, aka, a way define the response payloads using a entity types.
 - A single call can support multiple HTTP verbs, including support for various types of verbs GET, POST, DELETE, PUT 
 - Way to define Path/Query/Form based parameters
 - Way to define expected response codes or error codes
 - Way to define "Accepts" and "Content-type" headers on the services, as well as support for multiple versions of them
 - Multipart/form-data capability definition
 - Way to define security 

So, this little more than just execute a procedure of given name paradigm we may have took with WSDL and what is your pull request. This is much like subset of OData specification, I would call this a "ODate Lite"  or "Procedure Based REST Specification". OData goes much more deep with Entity based model, which close to ORM/JPA model, with strong querying capabilities. In a way, OData's _FunctionImports_ can be similar to the Swagger's API. Like many Swagger tools, we can drive this much further as we are doing with OData.

I apologize and retract my earlier statement about not needing separate translator, we should write a separate translator for this.  We need to use the existing "connector-ws" as the resource-adapter. I observed in your pull

- you only modeled "GET" calls, we need to support every type of http verb under a API call.
- "operationId" needs to be the name of the procedure.
- "description" needs to be in "setAnnotation" of the property
- "produces" needs to be captured in metadata, where it becomes aid select a serilizer or de-serializer to read responses
- Do not just return the Blob, since we have model for the pay load, design such that the procedure returns a resultset of the type definition defined.
- As per to read the contents to parse them, we could either write simple de-serializers, or figure out a way to use SQL/XML functions to automatically parse it. In OData I choose the de-serializers as they were available and it was easy,  but this could be our chance to use SQL/XML or JSON based functions. Writing a stax based parser should be easy enough for known types, obviously if the content type is not json or XML, the procedure would need to resort to returning the CLOB or BLOB or SQL/XML.
- Responses need to be validated against the definitions and codes and form the success or failures based on them
- I believe we can extract out some common code from OData V4 translator for document handling.
- I also think we can extract some common metadata properties for this from OData V4 translator
- security stuff seems interesting, we need to see how these could be integrated.

Next Steps:
- I do not think we can get much of this before 8.12 final, so I suggest we move the target. 
- Work on getting your current code into a making a new translator, as all your configuration module.xml etc is important, no need to do that work again.
- Make few changes as I suggested above and try to capture all the APIs
- See if there are libraries out there already to read the payloads in java for (json and xml. At a minimum for json, it is easy enough to write one if we can find, I did a quick search did not find any, need to check how the codegen project does)
- Once you get here, I will take look and see what parallels we get out of OData V4 translator etc, to make them work similar and share code. And iterate on some of the advanced features like security, multipart etc.

Tasks for me: Read the specification fully, I still only skimmed the api spec doc, I will read it next few days.


> Extend the Swagger support in the WS Translator
> -----------------------------------------------
>
>                 Key: TEIID-3520
>                 URL: https://issues.jboss.org/browse/TEIID-3520
>             Project: Teiid
>          Issue Type: Feature Request
>          Components: Misc. Connectors
>            Reporter: Ramesh Reddy
>            Assignee: Kylin Soong
>             Fix For: 8.12
>
>
> http://swagger.io is popular REST service description framework, it defines a specification http://swagger.io/specification/ for REST service definition. 
> Teiid WS translator should add the ability to read this file (like WSDL) and provide the REST methods as endpoints that can be consumed from Teiid.



--
This message was sent by Atlassian JIRA
(v6.4.11#64026)