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.
- Swagger 3.0 the specification in detail
- Swagger 3.0 Basis structure
- How to write your first spec
- Wat is new in 3.0
- The specification (on GITHUB)
- Dates in OpenAPI Files on Baeldung
- 5 laws of API dates and times by Jason Harmon
- JSON Schema specification
- openapi-generator-maven-plugin and Java date types
- OpenAPI and Java 8 time classes
- springdoc-openapi plugin
- Doing More With Springdoc-OpenAPI at DZone
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
- 10 Essentials When Creating an OpenAPI Specification
- Define a Single Error Response Schema with Zalando Problem based on application/problem+json
- How to conduct an API design review
- API-First Development with Spring Boot and Swagger
- OpenAPI Contract Example
- API first development with OpenAPI/Swagger Ordina
- Example JSON Schema
- Swagger Editor
- OpenAPI generator on GITHUB
- OpenAPI generator Maven plugin
- API First development with OpenApi and Spring Boot (mindset)
- Specification First: Make Life Easier with OpenAPI and Spring
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.
- Read about pros and cons
- Choosing between RAML and OAS
- MuleSoft Joins the OpenAPI Initiative: The End of the API Spec Wars
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.
- OpenAPI and JSON Schema: When to Use Which
- Prism support OpenAPI v3
- Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.
- All you need to know about Spring
- Springboot webtesting
- Mock MVC testing
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
More reads...
- Making full stack java development easier with JHipster
- Create full Microservice stack using JHipster Domain Language under 30 minutes
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 and Kubernetes and Istio
- Microservices using JHipster, Kubernetes, Istio
- And see what is all generated out of the box
- How to set up JHipster microservices with Istio service mesh on Kubernetes
- https://azure.microsoft.com/en-us/free/
JHipster documentation things
- Doing microservices with JHipster
- Technology stack
- Security
- OIDC
- JHipster Domain Language
- Using React
- React styleguide
- On production
- The presentation
- JDL examples
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:
- Error Handling for REST with Spring
- A Guide to the Problem Spring Web Library
- Understanding Spring’s @ControllerAdvice
- The simplest example on Zalando's problem handling and @ControllerAdvice
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)
Client Go
- Authenticating inside the cluster
- About apimechinary
- Springboot complete reference guide
- Predicate filters (howtodoinjava.com)
- Use JmsAutoConfiguration with Spring Boot 2 and Spring jms 5).
- Guide to JAXB springboot
- Using Lombok’s @Builder Annotation
- Introduction to Project Lombok
- Using the @Singular Annotation with Lombok Builders
- Make your class immutable with Lombok @value
- Multiple Entry Points in Spring Security
- Handling CSRF Token
- Spring Security and Angular
- Http Message Converters with the Spring Framework
- Introduction to Spring Cloud OpenFeign
- Fake Online REST API for Testing and Prototyping JSONPlaceholder
- CompletableFuture
- Guide To Java 8 Optional
- https://www.baeldung.com/java-optional-return
- Java 9 Optional API Additions
- https://www.baeldung.com/thread-pool-java-and-guava
- 90 New Features and APIs in JDK 11
- Java Collections Interview Questions
- An Introduction to the Java Collections Framework
- Java Collections
- Optional in Java 8 cheat sheet
- OpenAPI and JSON Schema: When to Use Which
- Documenting a Spring REST API Using OpenAPI 3.0
- OpenAPI 3 Documentation With Spring Boot Dzone
- OpenAPI Specification v3
- API-First Development with Spring Boot and Swagger
- Detecting Memory Leaks From a JVM Heap Dump
- Java Flight Recorder and Java Mission Control collect detailed runtime
- My Cucumber is better than your Fitnesse
- Best Behavior Driven Development (BDD) Tools and Testing Frameworks
- Auditing with JPA, Hibernate, and Spring Data JPA
- Getting started with Spring Data Envers
- Derived Query Methods in Spring Data JPA Repositories
- Intro to Gatling
- Run Gatling Tests From Jenkins