Careeroza

Real World Example

Docs as a Contract

Public APIs like Razorpay, Stripe and GitHub publish OpenAPI specs. Inside companies, the frontend and mobile teams read Swagger UI instead of asking backend developers, and tools such as OpenAPI Generator create TypeScript or Kotlin clients from the spec.

Example

Generate a TypeScript client for the ShopEase React app from the running API:

npx @openapitools/openapi-generator-cli generate -i http://localhost:8080/v3/api-docs -g typescript-fetch -o src/api/generated

Example output

[main] INFO  o.o.codegen.DefaultGenerator - Generating with dryRun=false
[main] INFO  o.o.codegen.TemplateManager - writing file src/api/generated/apis/ProductsApi.ts
[main] INFO  o.o.codegen.TemplateManager - writing file src/api/generated/models/CreateProductRequest.ts
[main] INFO  o.o.codegen.TemplateManager - writing file src/api/generated/models/ProductResponse.ts

ShopEase: Docs Only Outside Production

Swagger UI is great for dev and staging, but many teams switch it off in production (or protect it) so the full API map is not public:

Example

application-prod.yml

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

Example

curl -i localhost:8080/swagger-ui.html          # dev profile
curl -i https://api.shopease.in/swagger-ui.html # prod profile

Example output

HTTP/1.1 302 Found
Location: /swagger-ui/index.html

HTTP/2 404

Tip: Add the OpenAPI JSON to your CI build (download /v3/api-docs in a test) and fail the build when an endpoint changes in a breaking way.