Swagger Spec: An Embarrassment of Riches
Swagger Spec is a great way to define and document API projects. Your code and documentation live and ship together, allowing for rapid documentation and development. However, you might say it’s too good.
As your team and APIs using Swagger grow, so too do the challenges of wrangling that giant spec without breaking your APIs or driving your developers bonkers. Unfortinately, tools like the Swagger Validator start to break down for large, real worls specs 1. Here are some lessons I learned productionizing such large specs 2.
1. Use YAML, Not JSON
JSON is hard to read and easy to corrupt in large file sizes. YAML has:
2. Break Up Your Spec
Use the $ref includes functionality to compose multiple files into one spec. Break your spec into relevant sub sections (e.g. by entity type, department, etc). This will:
- Reduce checkin conflicts between developers
- Increase readability and maintainabilty
- More easily isolate spec errors
3. DRY: Don’t Repeat YAML
Swagger allows reuse of enums, so don’t repeat them in the
POST endpoints, and inside the data objects.
$ref references work for enums just like other Swagger object references.
paths: /widgets: get: parameters: - in: query name: shape required: true schema: $ref: '#/components/schemas/Shape' responses: '200': description: OK components: schemas: Shape: type: string enum: - round - square - triangle
4. Automate Swagger Spec Validation
Preemptively validate your spec, rather than wait until your API fails to start or object mapping errors throw 500’s in production.