Background
Sometimes it is useful to be able to export a SmartDocs model as an OpenAPI (formerly known as Swagger) specification. For historical reasons, SmartDocs stores models internally in its own format, which can be exported as JSON.
The Modeling API (part of the management server API with which SmartDocs communicates) was created with the ability to import not only OpenAPI documents but also WADL, and it can represent certain model patterns which OpenAPI cannot. When an OpenAPI document is imported into SmartDocs, there are some limitations to how the imported model is represented. Fortunately much of that metadata is saved as JSON blobs in customAttributes collections.
Exporting a SmartDocs model
In the Drupal developer portal, when logged in as an administrator, navigate the admin menu to Content > SmartDocs. For the model you wish to export, open the select-box on the right side of the screen and select “Export”. This will generate a JSON file for you in SmartDocs’ internal format.
Alternatively, you can directly export a model from the Modeling API via a curl call:
curl -u $USERNAME:$PASSWORD "https://api.enterprise.apigee.com/v1/o/$ORG/apimodels/$MODEL_NAME/revisions/$REVISION_NUM?expand=true" > model.json
The conversion script
We have lately been working on a stopgap script to perform this conversion from the command line. In its current incarnation, the script is written in PHP and can be found here:
gist.github.com/ossobuffo/aad5c65f7c9a23888b18156b324ff210
You can run this script as follows, presuming you named your exported model
model.json:
php SmartDocs2OpenAPI.php model.json > model.openapi.json
The output file (
model.openapi.json in this example) will contain a best-effort conversion of your model to OpenAPI.
Significant caveats
IMPORTANT: Apigee does not offer support for this script. It is provided to our customers as a courtesy.
Be sure to closely examine the output of this script—in particular, if the script cannot find a proper value for a required field, it will emit the string
FIXME.
The script makes broad assumptions regarding how scoped security schemas are applied. If you use scoped security schemas, you will want to carefully examine all method-level security values.
Because the internal representation models things slightly differently vis-à-vis the OpenAPI format, there may be other things to check. Many of these are minor and include:
- Parameter enum values may or may not be correctly populated.
- The “description” field of a method is generally preferred to the “summary” field, as the summary is usually a shortened version due to the character limitations of the OpenAPI Specification.
- The “format” attribute of integer parameters (i.e. “int32”, “int64”) is not preserved.
- The “collectionFormat” value for array parameters is sometimes not correctly saved.
- Body parameters with a declared schema may be incorrectly parsed. The correct “consumes” MIME type may be replaced by “application/x-www-form-urlencoded”.
- The optional “headers” collection on a method response is not preserved.
- The Model-level “tags” collection and “externalDocs” definition are not preserved.
- In schema definitions, properties of type “array” do not preserve their “xml” attributes.
- Definitions for “200 OK” responses are generally not saved unless their response body corresponds to a schema reference.
- The Modeling API does not return resources and methods in the same order in which they were defined in the original OpenAPI document, as the OpenAPI Specification is a hash rather than an array.
Taking a test drive
You can take your original OpenAPI document, import it into SmartDocs, export it, and run it through this script. Then compare your original document with the output of the script, using a JSON diff tool such as jsondiff.com.
Comments and suggestions
Feel free to add bug reports or suggestions to the Github gist.
LinkedIn
Twitter
