Chapter 2. Create a (Swagger) Spec
This section will help you to create a Swagger 2.0-compliant spec for your RESTful API, which is required to power ActiveDocs on your Developer Portal. If you only would like to read the code, all the examples are on Swagger Petstore example source code.
2.1. Credit where credit is due
3scale ActiveDocs are based on the specification of RESTful web services called Swagger (from Wordnik). This example is based on the Extended Swagger Petstore example and draws all the specification data from the Swagger 2.0 Specification document.
Swagger is not only a specification. It also provides a full feature framework around it:
- Servers for the specification of the resources in multiple languages (NodeJS, Scala, and others).
- A set of HTML/CSS/Javascripts assets that take the specification file and generate the attractive UI.
- A Swagger codegen project, which allows generation of client libraries automatically from a Swagger-compliant server. Support to create client-side libraries in a number of modern languages.
2.2. 3scale ActiveDocs and Swagger
ActiveDocs is not a Swagger replacement but an instantiation of it. With ActiveDocs, you don’t have to run your own Swagger server or deal with the UI components of the interactive documentation. The interactive documentation is served and rendered from your 3scale Developer Portal.
The only thing you need to do is to build a Swagger-compliant specification of your API, add it on your Admin Portal, and the interactive documentation will be all set. Your developers will be able to launch requests against your API through your Developer Portal.
If you already have a swagger-compliant spec of your API, you can just add it in your Developer Portal (see the tutorial on the ActiveDocs configuration).
3scale extended the Swagger specification in several ways to accommodate certain features that were needed for our own interactive API documentation:
- Auto-fill of API keys
- Swagger proxy to allow calls to non-CORS enabled APIs
2.3. Ready to create the spec of your API?
We recommend that you read first the original spec from the original source: the Swagger Specification
On the Swagger site there are multiple examples of specs. If you like to learn by example, you can follow the example of the Petstore API by the Swagger API Team.
2.3.1. Learning by example: the Petstore API
The Petstore API is an extremely simple API. It is meant as a learning tool, not for production.
The Petstore API is composed of 4 methods:
-
GET /api/pets- returns all pets from the system -
POST /api/pets- creates a new pet in the store -
GET /api/pets/{id}- returns a pet based on a single ID -
DELETE /api/pets/{id}- deletes a single pet based on the ID
Because Petstore is integrated with 3scale API Management, you have to add an additional parameter for authentication – for example, the standard User Key authentication method (there are others) sent in the headers.
You need to add the parameters:
user_key: {user_key}
The user_key will be sent by the developers in their requests to your API. The developers will obtain those keys on your Developer Portal.
Upon receiving the key, you will have to do the authorization check against 3scale using the Service Management API. (This starts to get into the integration. Check the /get-started/fast-track-integration[guide on integration] and API lifecycle for more details.)
For your developers, the documentation of your API represented in cURL calls would look like this:
However, if you want the documentation to look awesome like the Swagger Petstore Documentation, you have to create the following Swagger-compliant spec:
You can use this spec out-of-the-box to test your ActiveDocs. But remember that this is not your API.
At first it might look a bit cumbersome, but the Swagger spec is not complex at all. Learn more in the next section.
2.3.2. More on the Swagger specification
The Swagger specification relies on a resource declaration that maps to a hash encoded in JSON. Take the above petstore3scale.json as example an go step by step…
2.3.3. Swagger object
This is the root document object for the API specification. It lists all the highest level fields.
The host must be a domain and not an IP address. 3scale will proxy the requests made against your Developer Portal to your host and render the results. This requires your host and basePath endpoint to be whitelisted by us for security reasons. You can only declare a host that is your own. 3scale reserves the right to terminate your account if we detect that you’re proxying a domain that does not belong to you. This means that local host or any other wildcard domain will not work.
2.3.3.1. Info object
The Info object provides the metadata about the API. This will be presented in the ActiveDocs page.
2.3.3.2. Paths object
The paths object holds the relative paths to the individual endpoints. The path is appended to the basePath in order to construct the full URL. The paths may be empty, due to ACL constraints.
Parameters that are not objects use primitive data types. In Swagger, these are based on the types supported by the JSON-Schema Draft 4. There is an additional primitive data type "file" but it will work only if the API endpoint has CORS enabled (so the upload won’t go through api-docs gateway). Otherwise, it will get stuck on the gateway level.
Currently Swagger supports the following dataTypes:
- integer with possible formats: int32 and int64. Both formats are signed.
- number with possible formats: float and double
- string with possible formats, besides the unformatted version: byte, date, date-time, password
- boolean
2.3.4. Useful tools
The JSON Editor Online is quite good. It gives a pretty format to compact JSON, and it also provides a browser of the JSON object. We really recommend it if you are not well versed with the JSON notation.
Another great tool is the Swagger Editor. It lets you create and edit your Swagger API specification written in YAML inside your browser and preview it in real time. You can also generate a valid JSON spec, which you can upload later in your 3scale Admin Portal. You can either use the live demo version with limited functionality or deploy your own Swagger Editor.
2.3.4.1. Extension to the Swagger spec: Auto-fill of API keys
A very useful extension to the Swagger spec of 3scale’s ActiveDocs is the auto-fill of the API keys. On the parameters, you can define the field x-data-threescale-name with values app_ids, app_keys or user_keys depending on the authentication mode your API is in.
For instance, for the authentication mode App ID/ App Key you might want to declare "x-data-threescale-name": "app_ids" for the parameter that represents the application ID, and "x-data-threescale-name": "app_keys" for the parameter that represents the application key. Just like in the following snippet:
If you do so, ActiveDocs will automatically prompt the user of the ActiveDocs to log in to the Developer Portal to get their keys as shown in the screenshot below:
If the user is already logged in, it will show the latest five keys that could be relevant for them so that they can test right away without having to copy and paste their keys around.
The field x-data-threescale-name is an extension to the Swagger spec which will be ignored outside the domain of ActiveDocs.
