ABAP OpenAPI UI v1 released!

[geert-janklaps]

As mentioned in my previous blog post, I worked out a way to get Swagger / OpenAPI documentation for any SAP Netweaver Gateway OData service (both OData V2 and OData V4 services are supported).

Since this solution is based on two open source projects (Swagger UI and OData-openapi), I wanted to share my solution with the community as well.

So how does it work?

Unfortunately it is not possible to extend the SAP Netweaver Gateway framework using BADI's / User-exits on a global level to provide this functionality to all OData services at once at this point. (to make it work like for example a $metadata request)

So I created a separate transaction to list all activated OData services and provide the required functionality from within this transaction.

After installing the solution using abapGit the new transaction ZGW_OPENAPI will be available in the system.

This transaction provides following functionality:

• Determine OData version (V2 or V4)


• Filter activated services


• Display Swagger UI or OpenAPI JSON (e.g. for importing in an API management system)

After executing the report a list with services is displayed.



After clicking the service name, the BSP application containing the Swagger UI (or JSON) will be launched.



After that you'll be able to browse through the documentation and even try out each available call.

Example for a get entityset (with a filter string):



Result:

What are the advantages of using this solution?

The main advantages / reasons for using this solution are:

• No more (or at least less) work on documenting OData services


• Interactive documentation which also acts as a testing tool


• More user-friendly that standard testing tools


• Useable by key users with minimal technical skills


• Service definitions (JSON) can be downloaded and imported in for example Azure API Management

Where to get this project?

The project can be found here on GitHub (and needs to be installed using abapGit) and is MIT licensed.

If you experience any issues or want to contribute to the project please use the GitHub repository. Contributions are much appreciated!

Important notice: at the time of writing this solution was only tested on an S/4HANA 1809 system with embedded gateway (SAP_BASIS 753). Please leave a comment if you were able to get it working on lower levels (ABAP code used should be compatible with at least SAP_BASIS 740 Enhancement Pack 5) or on a SAP Gateway system.

Credits

As previously mentioned, the core of this project relies on two great open source projects:

• Swagger UI (for displaying the OpenAPI / Swagger documentation)


• OData-openapi (for converting OData metadata to OpenAPI / Swagger documentation)

The abapGit and abaplint projects, which I used to setup the Gitlab repository.

abapGit:

• Without this I wouldn't be able to share this solution


• Took over 95% of the repository rules and guidelines (these are just great by the way! In my opinion every open source ABAP project should apply these!)

abaplint:

• To validate that the development rules and guidelines are respected

Last but not least, I was allowed to use an S/4HANA 1809 development system for this personal project provided by TheValueChain NV (SAP Partner based in Belgium).

[gdegani]

Thanks a lot for releasing it! Looking forward to start playing with it! Would be great to be able to get an invite to the slack group. giovanni.degani at gmail

[geert-janklaps]

Hi Giovanni,

Let me know how it goes, I hope it works out of the box for your system!

I sent you an invite, you should be able to access the Slack group.

Best regards,

Geert-Jan Klaps

[sdfraga]

Hello 8d8214c7f9734f45be69f95cc0d5aeee ,

First of all let me thank you for your amazing work!!!

The tool is working fine in my system and I'm sure it will be very useful.

I've already done some changes, mainly in the ALV displayed to also add the package and the Created/Changed information. Don't know if you agree but if you like it I could try to make a PR.



Like this, the tool the tool is also useful for some monitoring tasks 🙂

I would like to add some suggestions on the behavior also:

When we launch the service, the system client used is always the client where the tool is running. If we have several clients in the Gateway, I have to manually change the URL by adding sap-client=XXX.

It would be nice if the tool discovers the correct client by checking the System Alias from the customizing. In the case we have multi-origin, a popup should be launched to ask the user for the client to be executed.

I will keep adding more ideas if they come up 🙂

Amazing job and THANK you for sharing this!!!

You should be in the TechEd presenting this!!!!!

Have a great week

Sérgio Fraga

 

[geert-janklaps]

Hi Sérgio,

Thanks for this great feedback! Your additions seem great, so a PR is welcome for sure!

Maybe create an issue tagged as new feature, with the new functionality you added and tag the issue in the PR. (so we can track what's been changed)

New ideas are always welcome, the ones you mentioned are for sure great! (just put them in an issue in the Gitlab repository so we can start integrating them)

Best regards,

Geert-Jan Klaps

[Steentje]

Hey Geert-Jan,

 

Thanks a lot for sharing this.

I had to adjust 3 little things in class ZCL_GW_OPENAPI:

1. Compile error as on our release  /iwbep/cl_v4_url_util  is not available (commented it out)


2.  /iwbep/if_v4_request_info=>ty_s_base_info has no attribute  uri_request (commented it out)


3. we have saml authentication in place so added  INSERT VALUE #( name = 'saml2' value = 'disabled' ) into table lt_params.  in the LAUNCH_BSP to be able to use basic logon.

This utility was a big help to be able to document my ODATA service !!

Greetings Danny.

[UweFetzer_se38]

I've opened an issue: Syntax Errors in ABAP Developer Edition (7.52)

[ana_isabel_garcia_martin2]

Hello Geert-Jan Klaps.

I don´t know if you could hep me.I have a problem with transformation files (XSLT). Although zgw_odatav2_to_v4.xslt.source.xml and zgw_odatav4_to_openapi.xslt.source.xml are right in my repository I can´t activate these objects. I see the code in sap and only appears 3 lines (is cutted).

I dont´t know if the problem is that the project was cloned to Github because I can´t connet to gitlab.

Thanks in advance.

Best regards.

 

[geert-janklaps]

Hi,

If the code is right in the repository it should work, did you trying updating abapGit to the latest version?

You could also try to download the Gitlab repository as a ZIP file and upload it into your system by creating a new offline project in abapGit.

Best regards,

Geert-Jan Klaps

[ana_isabel_garcia_martin2]

Hi,

 

I downloaded only these files and uploaded again to my repository. It works.

Before install this program I have already update abapgit.

 

Best regards.

 

[former_member239819]

Hi, Getting the following error when running the test service, any ideas?

Failed to load API definition.

Errors

Hide

Fetch error

Internal Server Error openapi.json?service=ZGW_OPENAPI_TEST_SRV&version=0001&group=&repository=

[geert-janklaps]

Hi adam.harkus,

Did you activate the test service in transaction /IWFND/MAINT_SERVICE? (the test service is not really relevant for actually using the solution, it's just a few dummy implementations which allow the solution to be tested without actually changing data in the system)

Best regards,

Geert-Jan Klaps

[former_member239819]

Hi.

Activated Gateway Service, still no joy though...

[former_member239819]

Checked ST22 and the error is:

Error in the ABAP application program.

The current ABAP program "ZCL_GW_OPENAPI================CP" had to be
terminated because it found a
statement that could not be executed.
In include "ZCL_GW_OPENAPI_METADATA_V2====CM005 ", in line 99 of program
"ZCL_GW_OPENAPI_METADATA_V2====CP ", the following syntax errors
have occurred:
Method "SET_METADATA_ACCESS_INFO" is unknown or PROTECTED or PRIVATE.

This is in line 99 of the _READ_METADATA method of ZCL_GW_OPENAPI_METADATA_V2

*   Initialize metadata access
    lo_transaction_handler->set_metadata_access_info(
        iv_load_last_modified_only = abap_false
        iv_is_busi_data_request    = abap_false
        iv_do_cache_handshake      = abap_true ).

Line 88 sets up lo_transaction_hander...

*   Initialize NetWeaver Gateway transaction handler
    DATA(lo_transaction_handler) = /iwfnd/cl_transaction_handler=>get_transaction_handler( ).  

The issue is set_metadata_access_info isn't defined as a method.

Is there a workaround?

Netweaver Version: 7.5 SP05

 

[HadrienP]

I had to manually install it, as the ABAPGIT couldn't communicate with gitlab.com in my SAP ERP (no sure why).  But after the installation it perfectly ran !

Thank you for sharing this amazing work !

Hadrien

[FrancoisAtAFP]

For others wondering what mileage they’ll get in older environments, we managed to get it working in NW 7.4 SP stack 22. A number of data type declarations needed to be swapped out, which would break OData V4 support, but as we were only after V2 support, we could live with that.

We found that /IWBEP/V4_MED_SERVICE_ID could be used where /IWBEP/V4_MED_REPOSITORY_ID or /IWBEP/V4_MED_GROUP_ID where specified (these don’t exist at our release level).

Similarly, references to tables /IWBEP/I_V4_MSRA and /IWFND/C_V4_MSGR could just be commented in program ZGW_OPENAPI_TOP with no ill effect for V2 usage. The body of methods such as ZCL_GW_OPENAPI_METADATA_V4->_READ_METADATA  or the selection from missing tables in the constructor of same class were commented for the same reason.

The only V2 related change required, was the call to lo_transaction_handler->set_metadata_access_info( ... ) in ZCL_GW_OPENAPI_METADATA_V2->_READ_METADATA which we just commented. No adverse impact was immediately obvious in our usage.

All this regrettable mangling of such beautiful code aside, the tool then produces lovely OpenAPI JSON specs for V2 services! Hats off to 8d8214c7f9734f45be69f95cc0d5aeee and contributors…

[FrancoisAtAFP]

Check out my post below on getting V2 support working in an even older environment than yours. We were able to just comment this call with no obvious ill effect...

[christoph_lffler]

An amazingly good piece of work - thank you, Geert-Jan!

I have two questions:

1. In the context we are using it, only a subset of the HTTP-methods (e.g. "GET" or "POST" only) will be implemented for most of the entities. Is there a way to suppress the non-implemented parts during output generation?
2. If the properties of the entities are linked to "real" data elements, is it possible to "dump" e.g. fixed domain values or a subset of the table keys of the table a domain is referencing into the example values?

   Or more general: (How) can the "example value" section of the openAPI document (the meta data) in oData V4(!) be influenced? I somewhere have seen an example where certain methods have been implemented in the *MPC_EXT or *DPC_EXT class to provide example values, but I can´t find it any more...

Any hint where to possibly add this functionality would be very appreciated... Thanks!

Edit:

What I would like to reach is something similar to this:

Edited openAPI description

Inspired by this blog by Andre Fischer I guess a possible approach could be:

1. add additional annotations in the DEFINE method of the services MPC_EXT class
2. replace the transformation ZGW_ODATAV4_TO_OPENAPI with an extended one

Any thoughts on this?

[PRAGSMATIC]

This is amazing work !!