OAS Open Api Spec Anatomy

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

OpenAPI first development

Following an API-first approach, we specify an API before we start coding. Via API description languages, teams can collaborate without having implemented anything, yet

RAML vs Swagger (OAS)

What is Swagger (OAS)?

Swagger—recently renamed to Open API** or OAS—is a type of framework that was designed to describe, produce, visualize, and consume RESTful web services. Referred to "language-agnostic," it has been developed to be read using a common language.

What is RAML?

RAML, or RESTful API Modeling Language, is a YAML-based language for describing RESTful APIs. As the name implies, it provides all the information necessary to describe RESTful or practically-RESTful APIs.

How did Swagger (OAS) become a standard?

MuleSoft, the creators of RAML, announced that they have joined the Open API Initiative. Created by SmartBear Software and based on the wildly popular Swagger Specification, the OpenAPI Initiative is a Linux Foundation project with over 20 members, including Adobe, IBM, Google, Microsoft, and Salesforce.

It should be obvious to followers of the API industry that this is a clear signal of convergence on the OpenAPI Specification (OAS). RAML will continue to provide additional modeling functionality on top of the OAS, but ultimately the contract will most likely be via OAS. Apiary — who is now part of Oracle — joined the Open API Initiative in 2016, bringing the OAS to back their documentation-focused Blueprint format.

Swagger built the project with three simple goals:

To be human readable. That means the spec had to be concise, organized, and clear enough that a "normal" person could understand it.

To be machine readable. This required structure and "rules" such that the specification itself could be interpreted to "do something useful" by a computer.

To be thorough enough to describe everything needed to consume or produce a REST API.

Open API V3 Prism

When designing APIs, it can be difficult to get meaningful feedback until you have a real API to share. That’s a complex process if you’re prototyping APIs in code. Prism is the mock server that enables you to have a test API that behaves how you specify without having to write a single line of code. For teams working in a CI/CD workflow, enterprise companies looking to get client-side teams involved as soon as possible, or small start-ups working on a big project with fewer resources, mock servers get feedback earlier in the development process and lead to more efficient results.

Prism is a set of packages for API mocking with OpenAPI v2 (formerly known as Swagger) and OpenAPI v3. For example, given an API description document you can spin up a mock HTTP server and respond realistically based on your requests. The big advantage to this is that Prism v3 now has a dynamic example generator which will produce a large variety of data output, rather than static data for each response. This allows for a larger range of instant feedback than ever before.

JHipster

JHipster is, in a nutshell, a high-level code generator built upon an extensive list of cutting-edge development tools and platforms.

The main components of the tool are:

Yeoman, a front-end scaffolding tool
Good old Spring Boot
AngularJS, the prominent Javascript framework. JHipster also works with React JS.

JHipster creates, with just a few shell commands, a full-fledged Java web project with a friendly, responsive front-end, documented REST API, comprehensive test coverage, basic security and database integration! The resulting code is well commented and follows industries best practices.

Other key technologies leveraged by it are:

Swagger, for API documentation
Maven, Npm, Yarn, Gulp and Bower as dependency managers and build tools
Jasmine, Protractor, Cucumber and Gatling as test frameworks
Liquibase for database versioning

JHipster and Kubernetes and Istio

JHipster documentation things

Spring REST API exception handling with Zalando and more

Problem is a small library with the purpose of standardizing the way Java-based Rest APIs express errors to their consumers.

A Problem is an abstraction of any error we want to inform about. It contains handy information about the error. Let's see the default representation of a Problem response:

Kafka Spring

Setting up and Customizing Jenkins X

Log on to Katacoda Istio training page, complete the first 2 steps and run these commands.

Install JX commandline tool

mkdir -p ~/.jx/bin
curl -L https://github.com/jenkins-x/jx/releases/download/v1.3.1096/jx-linux-amd64.tar.gz | tar xzv -C ~/.jx/bin
export PATH=$PATH:~/.jx/bin
echo 'export PATH=$PATH:~/.jx/bin' >> ~/.bashrc
jx version
jx upgrade cli

Check k8s compatibility

jx compliance run
jx compliance status
jx compliance results

Get Istio Ingress and install Jenkins X

cd /root
kubectl get svc -n istio-system -l istio=ingressgateway
Get your external IP
jx install --provider=kubernetes --external-ip {YOUR EXTERNAL IP} \
--ingress-service=istio-ingressgateway \
--ingress-deployment=istio-ingressgateway \
--ingress-namespace=istio-system
kubectl describe gateway -n istio-system
Finish off installation by providing your github and API keys
check if everything is there
kubectl get all -n jx
give it a go and create your first Spring Boot app....
jx create spring -d web -d actuator

Customizing Jenkins X

JX ships with a default Jenkins docker image jenkinsxio/jenkinsx which has many required plugins inside, I enhanced that original image with JIRA Pipeline steps plugin. Next I will provide my own build pack to providing custom pipeline steps for integrating these steps.

Adapt jenkinsx base image

git clone https://github.com/agilesolutions/jira-enabled-jenkinsx
cd jira-enabled-jenkinsx
docker build -t agilesolutions/jenkinsx .
docker login
docker push agilesolutions/jenkinsx
vi .jx/myvalues.yaml
Configure custom jenkinsx image, read config jenkins x custom jenkins image instructions.

Add custom build pack

git clone https://github.com/agilesolutions/jenkins-x-custom-buildpack
cd jenkins-x-customer-buildpack
Read the Pipeline Extension Model how extend the existing promotion pipelines with JIRA steps and to install that new build pack onto your jx namespace

Customizing existing pipelines

easiest way is to change the pipelines interactively on your existing build pack with jx create step. Sometimes you simply want to enhance release pipelines with additional steps to integrate with JIRA to track your release process on JIRA tickets. Read customising Pipelines.

TODO

Install JIRA pipeline steps plugin
Define your own Jenkins pipeline Shared Library to abstract away the JIRA steps work like adding a comment
jx create step -p release -l postbuild -m post "jiraAddComment" (jiraAddComment being one of the functions you expose through your custom shared library)