Ihre Browserversion ist veraltet. Wir empfehlen, Ihren Browser auf die neueste Version zu aktualisieren.

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 OASis 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:

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:

More reads...

Anyways, JHipster has a very nice feature for generating a full fledge microservice architecture using Netflix’s open source software and the Spring Cloud project, also including Docker.

JHipster microservices

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.

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

Add custom build pack

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)

 

Client Go

Hosted by WEBLAND.CH