Build-APIs-with-Swagger-and-OAS-3.0

Design-driven development.

Please refer to Instructions Notes for more useful references and links related to swagger.io

Checkpoints

1. Define consumer and server interaction via REST APIs.

   • standardization using OpenAPI Specification 3.0.
   • decide on paths, operations, securitySchemes, requestBodies, responseBodies, httpStatus to cover etc

2. How to use Swagger Hub.

   • Exporting client SDK and server stub.

3. Integrate client SDK into Angular application.

4. Implement server-side API

   • host and run Java machine on cloud.
   • Use API proxy.

---

Document List

• Notes on building APIs with Swagger and OAS 3

• The server stub for Spring from SwaggerHub was based on Java 7 (version correct as of my trial. Upgrading Java to use version 17 (current Long-Term Support version) resulted in broken codes with multiple deprecated elements. Issue reflected to Swagger. JIRA raised. Nothing happened. Some possible changes to pom.xml are recorded in Notes.txt.

• Below is a list of yaml files, in increasing order of difficulty, built using the Swagger Editor, to OpenAPI 3.0 Specification.

  • simpleAPI.yaml
    • intro to document structure of OAS 3.0
  • LearnSwaggerSG7-h-plus_blog_api-2.0.0-resolved.yaml
    • how to GET different elements of articles
    • new: put document Objects under components for reusability
  • blogPostAPI.yaml
    • how to POST a blog article
    • new: reuse of schemas under component for requestBody and responseBody
  • openapi.yaml
    • a more complete example
    • includes GET and POST operations.
    • different httpStatus codes for responseBodies
    • new: use of parameters, schemas, securitySchemes under component.

• Client SDK from SwaggerHub was used to build out an Angular application. Below are some screengrabs:

  • Angular client app-rest-api-product service typescript file
    • product.service.ts is part of client SDK auto-generated by Swagger Hub.
    • contains codes to call API for different paths and operations.
  • Angular app component typescript file
    • app.component.ts put together components for Angular application.
    • It imports product.service.ts from Swagger client SDK.
  • Angular app running locally in Visual Studio Code
    • what you should see with successful running of Angular application locally after import of client SDK into Angular frame.
  • Screengrab of angular app on localhost 4200
    • what you should see on webpage served by angular app.
    • Swagger virtual hub does not store images, so no images will display when Swagger virtual hub is used for testing.

• From SwaggerHub, I exported Java Spring server stub for API implementation on server-side. Screengrabs below:

  • ProductService java file with additional codes to build out server side API implementation
    • The java file with service layer code to call ProductAPIcontroller.java
    • ProductAPIcontroller.java is from SwaggerHub server stub
    • The only extra java file on server side
  • Server-side implementation response to GET products
    • shows successful running on localhost.
  • local machine running server stub API implementation
    • shows successful Java Spring Boot initialization in Visual Studio Code using server stub from Swagger Hub.
  • [Azure Vm for Swagger API](Azure Vm for Swagger API.jpg)
    • shows successful deployment of VM on Microsoft Azure that hosts API server
  • Azure Vm for Swagger API 2
    • shows details of deployed VM

---

API proxy

• Google Apigee Edge
• AWS API Gateway
• Azure API Management
• IBM API Connect
• Guides for integrating swagger.io with these service providers? I have included links in my Instructions Notes.

---

Useful references from Google:

OpenAPI Specification (formerly known as Swagger)
https://github.com/OAI/OpenAPI-Specification

Apigee Debug Tool (similar to cURL, Postman)
https://cloud.google.com/apigee/docs/api-platform/debug/trace?hl=en

Apigee organization - multi-tenancy architecture
https://cloud.google.com/apigee/docs/api-platform/fundamentals/organization-structure

Understanding APIs and API proxies
https://cloud.google.com/apigee/docs/api-platform/fundamentals/understanding-apis-and-api-proxies

API Keys
https://cloud.google.com/apigee/docs/api-platform/security/api-keys?hl=en

OAuth 2.0 framework
https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-home?hl=en

Intro to OAuth 2.0
https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-introduction?hl=en

OAuth2.0 The Big Picture
https://cloud.google.com/apigee/resources/ebook/oauth-big-picture-register?hl=en

IETF Specification (the original)
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-31

JWT (JSON Web Token) and JWS (JSON Web Signature)
https://cloud.google.com/apigee/docs/api-platform/reference/policies/jwt-policies-overview?hl=en

Security Assertion Markup Language
https://cloud.google.com/apigee/docs/api-platform/security/saml?hl=en

Apigee Integrated Developer portal
https://docs.apigee.com/api-platform/publish/portal/build-integrated-portal

Durpal - open source CMS
https://www.drupal.org/

JSON reference:
burningtree.awesome-json

./jq
Lightweight and flexible command-line JSON processor
https://stedolan.github.io/jq/