Offline API Documentation¶

Download OpenAPI specs and generate local documentation without a running server.

OpenAPI Spec Downloads¶

Each service exposes its OpenAPI 3.0 spec at /api-docs when running. For offline use, generate or export using the commands below.

Service	Port	Spec Path	Format
General Ledger	`8088`	`/api/v1/general-ledger/api-docs`	JSON
Product	`8083`	`/api/v1/products/api-docs`	JSON
Customer	`8082`	`/api/v1/customers/api-docs`	JSON
Deposit	`8081`	`/api/v1/deposits/api-docs`	JSON
Share	`8086`	`/api/v1/shares/api-docs`	JSON
System Setup	`8089`	`/api/v1/system-setup/api-docs`	JSON
Periodic Activity	`8087`	`/api/v1/periodic-activity/api-docs`	JSON
Bank & Branch	`8090`	`/api/v1/bank-branch/api-docs`	JSON
Common	`8091`	`/api/v1/common/api-docs`	JSON

Export a spec while service is running¶

# Export to file (replace PORT and SERVICE with values above)
curl http://localhost:PORT/api/v1/SERVICE/api-docs > docs/api-specs/SERVICE-openapi.json

Export all specs at once¶

$services = @(
  @{name="general-ledger"; port=8088; path="general-ledger"},
  @{name="products";        port=8083; path="products"},
  @{name="customers";       port=8082; path="customers"},
  @{name="deposits";        port=8081; path="deposits"},
  @{name="shares";          port=8086; path="shares"},
  @{name="system-setup";    port=8089; path="system-setup"},
  @{name="periodic-activity"; port=8087; path="periodic-activity"},
  @{name="bank-branch";     port=8090; path="bank-branch"},
  @{name="common";          port=8091; path="common"}
)

New-Item -ItemType Directory -Force docs/api-specs

foreach ($svc in $services) {
  Invoke-WebRequest `
    -Uri "http://localhost:$($svc.port)/api/v1/$($svc.path)/api-docs" `
    -OutFile "docs/api-specs/$($svc.name)-openapi.json"
  Write-Host "Exported $($svc.name)"
}

Generate HTML Docs (Redoc)¶

Redoc converts OpenAPI JSON to a standalone HTML file — no server needed.

# Install Redoc CLI (one-time)
npm install -g @redocly/cli

# Generate for a service
redocly build-docs docs/api-specs/deposits-openapi.json \
  --output docs/api-specs/deposits-redoc.html

# Generate all
for spec in docs/api-specs/*-openapi.json; do
  name=$(basename "$spec" -openapi.json)
  redocly build-docs "$spec" --output "docs/api-specs/${name}-redoc.html"
  echo "Built $name"
done

Open docs/api-specs/{service}-redoc.html in any browser — no internet required.

Generate Client SDKs (OpenAPI Generator)¶

Auto-generate TypeScript or Java client code from the OpenAPI specs.

TypeScript client¶

# Install
npm install @openapitools/openapi-generator-cli -g

# Generate TypeScript-Axios client for Deposit Service
openapi-generator-cli generate \
  -i docs/api-specs/deposits-openapi.json \
  -g typescript-axios \
  -o src/api-clients/deposit-client \
  --additional-properties=npmName=@neocore/deposit-client,npmVersion=1.0.0

Java client¶

openapi-generator-cli generate \
  -i docs/api-specs/deposits-openapi.json \
  -g java \
  -o src/api-clients/deposit-java-client \
  --additional-properties=groupId=in.fincuro.neocore,artifactId=deposit-client

Swagger UI — Local Static Server¶

Run Swagger UI locally using Docker (no live service needed — just point at a spec file).

docker run -p 8000:8080 \
  -e SWAGGER_JSON=/openapi/deposits-openapi.json \
  -v $(pwd)/docs/api-specs:/openapi \
  swaggerapi/swagger-ui

Open http://localhost:8000 to browse the spec interactively.

Postman Collection Export¶

Import OpenAPI specs into Postman for team-wide API testing.

Open Postman → Import → Link or File
Select docs/api-specs/{service}-openapi.json
Postman auto-generates a collection with all endpoints, request bodies, and examples
Set environment variable baseUrl = http://localhost:{port}
Export the collection as NeoCore-{service}.postman_collection.json for team sharing

springdoc-openapi Configuration¶

All NeoCore services use springdoc-openapi 2.3.0. Relevant properties in application.yml:

springdoc:
  api-docs:
    enabled: true
    path: /api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
  show-actuator: false

YAML path reference in pom.xml:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>