This tutorial is adapted from Web Age course Api Management Fundamentals for Architects Training.
To make RESTful services useful, Service APIs must be described and published. Client need to be able to find API descriptions. APIs must be described in sufficient detail so that clients can select services, create service requests, interpret service responses, choose service endpoints and understand service status codes.
Source: https://www.q-perior.com/en/blog/openapi-and-raml-in-comparison/
This approach starts by outlining the service operations and iteratively adding detail
#%RAML 1.0
—
title: Car Inventory API
baseUri: http://inventory.cars.com/{version}
version: v1
/cars:
/{id}
/make
/cars:
get:
/{id}
get:
post:
put:
patch:
delete:
/make
get:
/cars:
get:
query parameters:
make:
/{id}
get:
post:
put:
patch:
delete:
/make
get:
/cars:
/{id}
get:
description: Retrieve a specific car
responses:
200:
body:
application/json:
example: |
{
“data” : {
“id” : 1234,
“make” : “Ford”,
“model” : “Mustang”,
“year” : 1969
},
“success” : true,
“status” : 200
}
Swagger v.3 (Open API 3) is the latest Open API spec introduced early 2017.
-
Changes touched a number of areas:
-
Format:
-
OpenAPI 3 now specifies YAML should be 1.2
-
Better JSON Schema support (added: oneOf, anyOf, nullable, etc.)
-
URL structure
-
Components
-
Request format, etc.
-
Swagger 2.0 service descriptions can be ported to Open API 3 without much pain
-
See https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/ for more details
It is an Online tool. It displays OpenAPI service definition in editable window and shows operations on right side.
Expanding operations gives more details.
It shows model object details (types).
It is an online tool to generate server and/or client stubs. It supports multiple languages.
It is deployed with service and It has similar features to Swagger Editor.
Tools to test service
Enter values and execute requests:
with Swagger, you can view responses. Since this was a POST request a new resource was created
The response
No body
Status Code 201 – Created
Location header is the URI of the newly created resource
Swagger UI generate equivalent cUrl commands
The Swagger UI also displays the Open API service description in JSON. The JSON format used is not particularly readable.
In this tutorial we discussed
-
Describing RESTful APIs
-
History
-
RAML
-
Open API (Swagger)