Apidays Paris 2023 - OpenAPI Extensibility - The Good, The Bad and The Ugly, Oleg Nenashev, WireMock

Slide 1

Slide 1 text

OpenAPI Extensibility Oleg Nenashev, OpenAPI Initiative / Jenkins / WireMock The Good, The Bad, The YAMLy

Slide 2

Slide 2 text

2 * Testcontainers/AtomicJar is a WireMock partner

Slide 3

Slide 3 text

OpenAPI Extensions 101 3 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

OpenAPI Extensions 101 5 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

No content

Slide 8

Slide 8 text

> whoami @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Developer tools hacker Community builder & DevRel consultant #RussiansAgainstPutin #StandWithUkraine

Slide 9

Slide 9 text

Kudos to Sponsors of this visit 9 https://www.openapis.org/ https://www.wiremock.io/

Slide 10

Slide 10 text

No content

Slide 11

Slide 11 text

OpenAPI Extensions github.com/OAI/OpenAPI-Specification/blob/main/guidelines/v2.0/EXTENSIONS.md 11 spec.openapis.org/oas/latest.html#specification-extensions

Slide 12

Slide 12 text

Examples… 12

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

14 Wait, it’s all just Swagger? OpenAPI 3 Extensions

Slide 15

Slide 15 text

So, but what’s ugly? ● No official v3 Documentation ● V2 specification has not been updated in ages 15

Slide 16

Slide 16 text

Specification is an inspiration ● Nobody cares where “x-” fields are supported or not ● Almost everything in “x-” fields? Why not ● Encrypted data in spec? Why not? ● Contribute back? Why? 16 Image source: https://dev.to/meatboy/what-are-mo dern-examples-of-embrace-extend- and-extinguish-21j3

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

18 jenkins.io

Slide 19

Slide 19 text

Who is Mr. Jenkins? ●Automation server/framework ●Popular CI/CD tool ●Open-source ●Big community ●More than 1700 plugins ●Part of the Continuous Delivery Foundation

Slide 20

Slide 20 text

Slide 21

Slide 21 text

21 New demands Shift left Jenkins evolved … but not fast enough for early adopters API

Slide 22

Slide 22 text

Shifting Gears: Making Changes Aug 31, 2018 – Kohsuke Kawaguchi, “Jenkins: Shifting Gears” https://jenkins.io/blog/2018/08/31/shifting-gears/

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

Swaggy Jenkins Unofficial API specification Client applications generated from it 24 github.com/cliffano/swaggy-jenkins

Slide 25

Slide 25 text

Swagger OpenAPI specs in Jenkins May plugins implement Swagger/Open API specs Recommendation, but not a standard Too difficult to maintain 25 https://www.jenkins.io/blog/2019/08 /16/folder-auth-plugin/#rest-apis-wit h-swagger-support

Slide 26

Slide 26 text

2,000+ components with REST API 26

Slide 27

Slide 27 text

We wanted to use OpenAPI at Scale ● Jenkins has in-house web framework (Stapler + Jetty) ● Integrations would benefit from a specification and code generator ● We could merge all specifications live for each service instance 27

Slide 28

Slide 28 text

OpenAPI in Google Summer of Code 28 jenkins.io/sigs/gsoc

Slide 29

Slide 29 text

What did I try to put in “x-”? ● Authorization model ● Feature flags ● Conditions ● Stateful behavior ● … 29 Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/

Slide 30

Slide 30 text

30 Source: https://medium.com/10-minutes-qa-story/api-testing-from-scratch-api-anatomy-f220856ce9b3

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

Open API as Code ● JSON/YAML extensions are not great ● OpenAPI specifications are huge and not sustainable as is ● It is an interexchange format ● 99% of specifications are generated by tools ● OpenAPI DSLs 32

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

35 WireMock 101 WireMock is a tool for building mock APIs 5M+ downloads a month Available beyond Java, inc Rust or Golang You can can: ● Create stable development environments ● Isolate yourself from flakey 3rd parties ● Simulate APIs that don't exist yet wiremock.org

Slide 36

Slide 36 text

36 wiremock.org/docs/stubbing IF (request_url) THEN (response) * * it gets MUCH more complex WireMock Config JSON: Client library response request Client App Mock API Server HTTP/2

Slide 37

Slide 37 text

WireMock in Java 37 wiremock.org/docs/stubbing

Slide 38

Slide 38 text

WireMock Features 38 wiremock.org/docs

Slide 39

Slide 39 text

WireMock Ecosystem & Features 39 wiremock.org/docs

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

WireMock Cloud by WireMock Inc. 41 ● WireMock creator is a co-founder of the Inc. ● WireMock Cloud - SaaS for end-to-end API mocking ● Private beta: K8s Edition for managed / on-premises ● OpenAPI co-development wiremock.io

Slide 42

Slide 42 text

WAS 42 wiremock.io/post/creating-mock-api-templates-from-openapi

Slide 43

Slide 43 text

NEW: API Co-Development 43 wiremock.io/post/ship-api-dependent-features-more-efficiently-with-mock-first-api-prototyping NOTE: Vendor neutral talk, no demo

Slide 44

Slide 44 text

OpenAPI in WireMock Cloud ● Full import of OpenAPI => mock API ● Bidirectional, incremental OpenAPI <=> mock API generation ● Request and response validation ● Generation of both specific and loose matching stubs 44 NOTE: Vendor neutral talk, no demo

Slide 45

Slide 45 text

OpenAPI Spec Extensions in WireMock Cloud ● x-faker - specify the random value generator for a schema element ● x-parameter-values - to specify values of the request parameters associated with a specific response example ● x-wiremock-hash - tracking of changes for synchronization 45 NOTE: Vendor neutral talk, no demo

Slide 46

Slide 46 text

Slide 47

Slide 47 text

No content

Slide 48

Slide 48 text

48 github.com/OAI/moonwalk

Slide 49

Slide 49 text

OpenAPI 4 “Moonwalk” ● Eliminate complexity ● Support APIs that have different responses based on query parameters, headers and request bodies. ● Support a broader range of URL design patterns ● Reduce nested structures to improve readability and editability ● Improve reusability of request and response patterns 49 https://github.com/OAI/moonwalk

Slide 50

Slide 50 text

Moonwalk - My wishlist ● ASAP: Get it released! ○ Later: Other stuff is later ● OpenAPI DSL ● Adopt popular extensions ● Built-in Authorization ● Connect Parameters/Responses/Examples ● Learn from API Modeling tools 50

Slide 51

Slide 51 text

Learn from API Modeling 51 wiremock.org/docs

Slide 52

Slide 52 text

No content

Slide 53

Slide 53 text

Takeaways 53 ● OpenAPI Extensions are a an engine to consider ● Extensions help where the specification does not ● OpenAPI 4 Moonwalk will change the things a lot!

Slide 54

Slide 54 text

It’s [always] a great time to contribute! communityinviter.com/apps/open-api/openapi openapis.org/participate/how-to-contribute 54

Slide 55

Slide 55 text

How to participate NOW ● Share feedback! ● Evolve the spec beyond Swagger ● Adopt the spec 55