Schema-First API Design
with OpenAPI / Swagger
API Design process
What is OpenAPI?
Introduction
Design
Spec
Tools
Conclusion
Writing OpenAPI specs
Summary and further learning
Tooling around OpenAPI
You’re building an API
Adding a new feature to the API
Is there a better way to do this?
Schema-First API Design
The Schema-first API design approach means writing your API definition first in one of many API Specification languages before writing any code.
Benefits of the Schema-First Approach
Iterate faster in teams
Generate Artifacts
Generate API Tests
You can generate mock services for clients to work with, even before backend components are ready.
Your API Specification can be used to generate functional tests for the API.
Your API Specification can be used to generate SDKs, documentation, and server scaffolds.
API Specification Languages
API Design process
What is OpenAPI?
Introduction
Design
Spec
Tools
Conclusion
Writing OpenAPI specs
Summary and further learning
Tooling around OpenAPI
OpenAPI / Swagger
What’s in an OpenAPI Specification?
openapi: 3.0.0��info:� title: Sample API� description: Optional multiline or single-line description� version: 0.1.9��paths:� /users:� get:� summary: Returns a list of users.� description: Optional extended description in CommonMark or HTML.� responses:� '200': # status code� description: A JSON array of user names� content:� application/json:� schema:� type: array� items:� type: string
editor.swagger.io
Writing an OpenAPI Specification: openapi
openapi: 3.0.0
The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
Writing an OpenAPI Specification: info
info:� title: Sample Pet Store App� version: 1.0.1� description: This is a sample server for a pet store.� termsOfService: http://example.com/terms/� contact:� name: API Support� url: http://www.example.com/support� email: support@example.com� license:� name: Apache 2.0� url: http://www.apache.org/licenses/LICENSE-2.0.html
The info section provides general information about the API.
Writing an OpenAPI Specification: paths
paths:� /products/{id}:� get: <operation>�� /orders:� post: <operation>
The paths section contains the endpoints such as /products and operations are the HTTP methods such as GET, POST, DELETE
Writing an OpenAPI Specification: paths
paths:� /products/{id}:� get:� operationId: getProductById� parameters:� - name: id� in: path� description: Product ID� required: true� schema:� type: integer� format: int64� responses:� '200':� content:� application/json:� schema:� $ref: '#/components/schemas/Product'
Each operation documents any parameters for the operation, the different kinds of responses, and other metadata.
Writing an OpenAPI Specification: components
components:� schemas: # Schema object definition� Pet:� type: object� properties:� name:� type: string� petType:� type: string� required:� - name� - petType
The components section lets you define common data structures used in your API. They can be referenced via $ref whenever a schema is required:
$ref: '#/components/schemas/Pet'
editor.swagger.io
Tooling around OpenAPI
And more!
Swagger Codegen
Swagger UI
There are tons of libraries and frameworks that support the OpenAPI ecosystem.
Generates server stubs and client libraries in over 40 languages / platforms.
Generate interactive API documentation that lets users try out API calls in the browser.
API Design process
What is OpenAPI?
Introduction
Design
Spec
Tools
Conclusion
Writing OpenAPI specs
Summary and further learning
Tooling around OpenAPI
Schema-First API Design
with OpenAPI / Swagger
Q&A