Swagger AEM OSGI

Swagger AEM OSGI is an OpenAPI specification for configuring Adobe Experience Manager (AEM) API.

This specification is used to generate client libraries for Ruby, Python, JavaScript and Java using OpenAPI Generator, with the build and release targets of Swaggy C.

Learn more about Swagger AEM OSGI:

• Installation
• Usage
• Testing
• Frequently Asked Questions
• Versions History
• Presentations

Swagger AEM OSGI is part of AEM OpenCloud platform but it can be used as a stand-alone.

The Swaggy C targets in Makefile generate the clients with the OpenAPI Generator Docker image, so they need Docker, plus Node.js, Python and Ruby to build and test the clients. CI runs them in the cliffano/studio Docker image.

The Java targets in Makefile-extras need Java and Apache Maven. Run them inside the aem-platform-buildenv Docker image, as CI does.

Each release publishes every client with the same version:

Language	Package	Getting Started
Ruby	swagger_aem_osgi	README
Python	swaggeraemosgi	README
JavaScript	node-swagger-aem-osgi	README
Java	com.shinesolutions:swaggeraemosgi4j	README

The API documentation is published to GitHub Pages.

The specification is specification/swagger-aem-osgi.yml. Each client is generated into clients/<language>/generated using its clients/<language>/conf.json.

$ make clean deps init-spec generate-primary build-ruby

The Java client is only regenerated by make generate. The Java targets build, test and publish the committed client as it is.

See the Getting Started README of each client above, and the examples in examples for calling AEM with the JavaScript, Python and Ruby clients.

Unit tests are generated by OpenAPI Generator along with the client code. The tests in test stub the HTTP calls, so they need no AEM instance.

• Q: How can I generate a new OpenAPI specification ?

  A: To generate a new OpenAPI specification e.g. when there is a new release of AEM you simply can run the tool api_generator.rb.

  Usage:

  # ruby tools/openapi_spec_generator.rb --in templates/api.yml --out conf/api.yml'

• Q: How can I define a custom AEM host, user and password to generate OpenAPI Spec file ?

A: To run the OpenAPI Spec generator against a defined AEM Host or to define your own username and password to authenticate against AEM you need to define them as environment variables

usage:

aem_verify_ssl=false
aem_protocol=https \
aem_host=author.sandpit.aemopencloud.net \
aem_port=443 \
aem_username=admin \
aem_password=admin \
ruby tools/openapi_spec_generator.rb --in templates/api.yml --out conf/api.yml

Changes in each version are described in CHANGELOG.md.

Since 2.0.0, the specification and all clients are released together with one version, tagged <version> in git, e.g. 2.1.0. Versions follow Semantic Versioning: use a major release for breaking changes, minor for new features and patch for fixes. Between releases, the version files hold the next pre-release version, e.g. 2.1.1-pre.0. Before 2.0.0, the clients were released separately, with tags prefixed by the language, e.g. ruby-1.0.0 and python-1.0.0.

Versions are managed with RTK, configured in .rtk.json. It sets the release version in the specification, every clients/<language>/conf.json, the Java client's pom.xml, swaggy-c.yml and CHANGELOG.md, and sets the publish workflows to check out the tag. It commits and tags the release, then commits the next pre-release version with the publish workflows back on main.

The publish workflows hold the credentials, so a release from GitHub Actions needs none locally. To publish the Java client yourself, you need:

• A GPG key for signing, with its public key on a keyserver such as keyserver.ubuntu.com (Maven Central verifies signatures against it)

• A Maven Central Portal user token for the com.shinesolutions namespace

• Both are read from environment variables only, never from files. Enter them in your shell, so the values stay hidden and out of your shell history:

  # GPG private key: run this, paste the whole key including the
  # -----BEGIN/END PGP PRIVATE KEY BLOCK----- lines, press Enter, then Ctrl-D
  $ stty -echo; MAVEN_GPG_KEY="$(cat)"; stty echo; export MAVEN_GPG_KEY
  
  # GPG passphrase and Central Portal user token: type or paste each value, then press Enter
  $ read -rs MAVEN_GPG_PASSPHRASE; export MAVEN_GPG_PASSPHRASE
  $ read -rs MAVEN_CENTRAL_USERNAME; export MAVEN_CENTRAL_USERNAME
  $ read -rs MAVEN_CENTRAL_PASSWORD; export MAVEN_CENTRAL_PASSWORD
  

Run the Java targets in aem-platform-buildenv, from this repository's directory. It passes the variables through by name:

$ docker run --rm -it -v "$(pwd)":/workspace/swagger-aem-osgi -w /workspace/swagger-aem-osgi \
    -e MAVEN_GPG_KEY -e MAVEN_GPG_PASSPHRASE -e MAVEN_CENTRAL_USERNAME -e MAVEN_CENTRAL_PASSWORD \
    shinesolutions/aem-platform-buildenv:6.5.0 bash

1. Start from an up-to-date main with a green CI build and a clean working tree. Check that the ## Unreleased entries in CHANGELOG.md describe everything in this release.

2. Optionally, check signing and the Maven Central upload of the Java client without publishing it:

   $ make -f Makefile-extras publish-java-test
   

   Then drop the test deployment with publish-java-drop. The upload counts towards the organisation's Maven Central publishing limits.

3. Create the release, either:

   • In GitHub Actions, run the Release Major, Release Minor or Release Patch workflow. It runs RTK and pushes the commits and the tag. Then git pull --tags to fetch them.
   • Or locally with RTK installed, choosing release-major, release-minor or release-patch:

     $ make release-minor
     $ git push --follow-tags
     

4. The pushed tag triggers the publish workflows:

   Workflow	Publishes to
   Publish API Documentation	GitHub Pages
   Publish JavaScript	npm
   Publish Python	PyPI
   Publish Ruby	RubyGems
   Publish Java	Maven Central, with the SHINEOPENSOURCE_MVNREPOSITORY_TOKEN_USERNAME, SHINEOPENSOURCE_MVNREPOSITORY_TOKEN_PASSWORD, SHINEOPENSOURCE_MAVEN_GPG_KEY and SHINEOPENSOURCE_MAVEN_GPG_PASSPHRASE GitHub secrets

   To upload the Java client yourself instead, in aem-platform-buildenv:

   $ git checkout <version>
   $ make -f Makefile-extras build-java test-java publish-java
   $ git checkout main
   

5. Publish the Java client on Maven Central. Maven Central validates the upload (signatures, checksums, POM, sources and javadoc), then the deployment waits at central.sonatype.com → Publishing → Deployments: click Publish to release it, or Drop to discard it without publishing. A published version can't be changed or removed. Without a Central Portal login, use the user token and the deployment ID printed by publish-java:

   $ make -f Makefile-extras publish-java-status DEPLOYMENT_ID=<id>
   $ make -f Makefile-extras publish-java-drop DEPLOYMENT_ID=<id>
   

6. Unset the secrets when you are done: unset MAVEN_GPG_KEY MAVEN_GPG_PASSPHRASE MAVEN_CENTRAL_USERNAME MAVEN_CENTRAL_PASSWORD

• Beyond AEM Curl Commands at Adobe Immerse'18
• Building An AEM API Clients Ecosystem at Adobe Experience Cloud Meetup - 5th Edition