## Build an API client from Swagger 1.2 specs ### Learnings about Swagger 1.2 definition files Usually, _api-docs_ is the entry file when called in the browser. This is an example of a URL of the file: ```txt http://hostname:port/api/api-docs ``` In Swagger 1.2, this is the so-called **resource file**. That file's content could look like the following example. `apiVersion` refers to the version of the REST API, while `swaggerVersion` refers to the format of the Swagger definition. `apis` describes the available endpoints. ```json { "apiVersion": "1.0", "swaggerVersion": "1.2", "apis": [ { "path": "/path/to/first-endpoint", "name": "Meaningful/Name", "description": "Some description" }, { "path": "/path/to/another-endpoint", "name": "Another/Name", "description": "Some description" } ] } ``` In this case, the `path` fields reference the file paths of the respective endpoint's declaration files. URL-wise, those are sub-folders of _/api-docs_. Example: ```txt http://hostname:port/api/api-docs/path/to/first-endpoint ``` The structure of such an endpoint declaration file looks like this: ```json { "models": {}, "apiVersion": "1.0", "swaggerVersion": "1.2", "apis": [], "basePath": "http://hostname:port/api", "resourcePath": "/path/to/first-endpoint" } ``` - `models` contains the definitions/structure of the types used in the `apis` array - `basePath` is the base path of the REST API - `resourcePath` is the path of the endpoint ### Learnings from generating the API client This describes the steps necessary to generate an API client from a Swagger definition at version 1.2. At first glance, that sounds like an easy task, but it comes with a pitfall: With a Swagger definition at version 1.2, the API definition is split across multiple files. I found that API client generators struggled with creating an API client directly from those files and that the conversion works a lot better with a single 2.0 definition file. So, I had to first traverse all 1.2 definition files on the server and pull them to the local file system. From there, I was able to convert the 1.2 definition to version 2.0, which resulted in a single API definition file to generate an API client from. However, along the way, I found that the original definition files were not in good shape and the process of file conversion and client generation is bumpy. I needed to make adjustments in several places before and after the API client generation. This is the procedure that I went through: 1. Traverse definition files and store locally 2. Manually check and adjust the definition files 3. Convert the definition files from version 1.2 to 2.0 4. Validate the 2.0 definition file 5. Generate API client 6. Adjust API client (adjust `import` statements, patch broken code)