AEM Swagger

[nsvsrk]

Hi all,

I understand that Swagger is an API documentation.

What are its use cases for AEM?

What is supplied by the back end team to the Front end team in terms of Swagger? JSON fie or something different?

How the back end team prepares it?

How to configure a Swagger as a proxy for AEM?

What is the overall process?

Implementation walkthrough of any AEM use case will help.

I highly appreciate all your responses.

Thanks,

RK.

[daniel-strmecki]

Hello,

Open API or Swagger is an API documentation tool that makes it simple to generate API documentation and share it with the teams using the API, like frontend. Open API can be used in any language or framework, it is not specific to AEM any way.

AEM internally also uses Open API and docs can be found here: https://developer.adobe.com/experience-cloud/experience-manager-apis/api/stable/sites/

In case you are developing custom APIs in AEM, you can of course use Open API for documentation. There are plenty of articles how to integrate it in a Java/Maven project, for example https://www.baeldung.com/java-openapi-generator-server 

Hope this helps,

Daniel

[nsvsrk]

Thanks Daniel.

I agree Swagger is an pen source product that could be used in any domain or product and has got nothing to do only for aem.

Let us say I am implementing project in Adobe using aem, analytics, target, campaign and Adobe Commerce.

Please help me by identifying use cases in this scenario.

Ex: Adobe Commerce could implement apis and share the documentation using Swagger.

At a high level how this whole process works.

Adobe Commerce uses Swagger to generate documentation?

Is it just documentation of kind of a proxy that could receive calls from aem and generates a reply on its own?

Is this swagger just a json text file or an executable?

How aem invokes these apis?

Without this, what would we do and this identifies our original pain points and swagger value add for aem.

All this at a high level only.

I am aware that it is like a journey, but it helps me understand the system and its value add.

I really appreciate all your time and effort.

Thanks,

RK.

[daniel-strmecki]

Hi @nsvsrk,

I am not an expert on Open API, but on a high level I've used it to:

• provide documentation to the team using the APIs my team has developed
  • this is usually done through an API specification URL available on the same server where the API is running
• generate the client code for making API calls, for example in Java or JavaScript

It's primarily used to document APIs in an easy and standard way. I am not aware of any use cases where it is used as a proxy. I would say this is probably not the purpose of Open API. Although you could probably use the Open API documentation for creating a proxy/gateway.

Good luck,

Daniel

[nsvsrk]

Thanks Daniel.

• provide documentation to the team using the APIs my team has developed:

I guess it is done automatically. Kindly share steps for this at a high level.

• generate the client code for making API calls, for example in Java or JavaScript

It is also done automatically. Kindly share steps for this at a high level.

Thanks,

RK.

[Rohan_Garg]

Hi @nsvsrk,

Swagger is a tool for API Development, much like Postman documenting how an API works.
In terms of what is provided by the backend team will be a Swagger UI URL - /swagger/index.html

This is based out of /swagger/v1/swagger.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "TestAPI",
    "version": "1.0"
  },
  "paths": {
    "/api/APITest/RunEstimates": {
      "post": {
        "tags": [
          "APITestEstimatorApi"
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/JToken"
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/JToken"
                }
              }
            },
            "text/json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/JToken"
                }
              }
            },
            "application/*+json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/JToken"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }

This Open API Specification would then correspond to the REST Endpoint - 

Follow Getting Started to create APIs from scratch.

AEM APIs are also documented in OpenAPI specification as mentioned by @daniel-strmecki

Hope this helps!

[kautuk_sahni]

@nsvsrk Did you find the suggestions helpful? Please let us know if you require more information. Otherwise, please mark the answer as correct for posterity. If you've discovered a solution yourself, we would appreciate it if you could share it with the community. Thank you!

[nsvsrk]

Hi @kautuk_sahni,

I am still not clear on the below:

After we create Swagger file, how (in what format) will it be shipped to front end team? YAML file?

front end team receives it and looks at the documentation of apis, like how to invoke, parameters, teir types, return values, etc.

Apart from this, could they use it as an executable? Like invoking apis the yaml file and getting responses programmatically run time?

My understanding is that it being just a yaml file, is not invocable.

I understand that client side code could be created automatically using Gen tool.

Appreciate all your replies.

Thanks,

RK.

[Rohan_Garg]

Hey @nsvsrk, let me try to break it down further hopefully - 

1. Swagger definitions can be both YAML or JSON. That defines all the schemes, host, rest end points etc. basically everything you need to define the API.
You can refer to the blog - https://swagger.io/blog/api-development/getting-started-with-swagger-i-what-is-swagger/

Also, the sample swagger collection exposed at URL - https://petstore.swagger.io/#/pet/uploadFile

2. You can follow the blog at https://blog.developer.adobe.com/using-external-data-sources-in-aem-forms-with-openapi-swagger-speci... to see how in AEM Forms the swagger file is used to configure the data source to pull in data via REST APIs directly in an AEM Form.

Hope this helps!

Rohan Garg