Creating Swagger/OpenAPI Specification for Mobile App API
OpenAPI specification—a contract between mobile client and server. Without it, each backend change potentially breaks app, and you find out only when user crashes.
Why YAML File in Repository Matters More Than Wiki Page
OpenAPI 3.1 spec—machine-readable document. From it, automatically generated: TypeScript types for React Native via openapi-typescript, Kotlin client via openapi-generator, Swift client via CreateAPI or Apple's swift-openapi-generator. Wiki page can't do that.
Another advantage: contract testing. Tools like Dredd or Schemathesis take spec and check real server matches it. Catches backend regressions before mobile team learns about changes.
How to Build Spec
If backend on Laravel: use darkaonline/l5-swagger with PHPDoc annotations, or write spec manually in openapi.yaml and validate via spectral lint. Second path preferable for cleanliness—annotations in code quickly become garbage.
If backend on NestJS: @nestjs/swagger decorators give spec almost automatically, but need discipline: every DTO must be described via @ApiProperty(), else schema leaky.
For existing API without spec: snapshot existing behavior—run real requests via mitmproxy, parse traffic, generate draft via har-to-openapi. Draft inexact but gives 70% work.
Typical openapi.yaml structure for mobile project:
openapi: 3.1.0
info:
title: Mobile App API
version: 2.1.0
servers:
- url: https://api.example.com/v2
description: Production
- url: https://staging.api.example.com/v2
description: Staging
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Separately describe components/schemas for reusable models, don't inline schema in every endpoint. Critical when generating clients—duplicate inline schemas give duplicate types.
CI/CD Integration
Spec lives in git with code. In pipeline add two steps: spectral lint openapi.yaml checks conformance to rules (no operations without operationId, all responses documented), schemathesis run runs fuzzing tests against staging. Failed test—PR doesn't merge.
Timeline creating spec from scratch for mobile app API: 1-2 weeks depending on endpoint count and existing documentation.