Writing OpenAPI (Swagger) Specification Tutorial Series - Part 8

Splitting specification file

By Arnaud Lauret, August 2, 2016

With previous posts we have learned to produce an OpenAPI specification containing all OpenAPI specification subtleties. Some specification files may become quite large or may contain elements which could be reused in other APIs. Splitting a specification file will help to keep it maintainable by creating smaller files and also help to ensure consistency throughout APIs by sharing common elements.

Writing OpenAPI (Swagger) Specification Tutorial Series

This tutorial teaches everything about the OpenAPI 2.0 Specification (fka. as Swagger), most of what you’ll read here can still be applied on version 3.

If you’re a bit lost in the specification (version 2 or 3), take a look at the OpenAPI Map:

In previous parts we’ve learned to create highly accurate API description which can become quite large or may contain elements that can be reused, in this eighth part we’ll learn how to split an OpenAPI specification file into smaller and reusable elements.

JSON Pointers

In part 3 - Simplifying spefication file we have learned how to simplify the specification by creating reusable elements. In the example below, the Person definition is defined once in definitions and used as

A body parameter in POST /persons
A response schema in GET /persons/{username}
A sub-elements in Persons definition

swagger: "2.0" info: version: 1.0.0 title: Simple API description: A simple API to learn how to write OpenAPI Specification schemes: - https host: simple.api basePath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. parameters: - name: pageSize in: query description: Number of persons returned type: integer - name: pageNumber in: query description: Page number type: integer responses: 200: description: A list of Person schema: $ref: "#/definitions/Persons" post: summary: Creates a person description: Adds a new person to the persons list. parameters: - name: person in: body description: The person to create. schema: $ref: "#/definitions/Person" responses: 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. parameters: - name: username in: path required: true description: The person's username type: string responses: 200: description: A Person schema: $ref: "#/definitions/Person" 404: description: The Person does not exists. definitions: Person: required: - username properties: firstName: type: string lastName: type: string username: type: string Persons: type: array items: $ref: "#/definitions/Person"

To use the Person definition in these different places, we use a JSON Pointer (defined by RFC6901):

 $ref: "#/definitions/Person"

This pointer describes a path in the document, pointing to Person in definitions which is as the root (#) of the current document.

But JSON pointers are not only meant to point something within the current document, they can be used to reference something in another document.

Basic splitting

Let’s see how we can split the file we created in part 3

Referencing a local file

We can create a person.yaml file containing the Person definition:

Person: required: - username properties: firstName: type: string lastName: type: string username: type: string

Then we can remove the Person definition in definitions and replace all existing references to person #definitions/Person by a reference to Person in the person.yaml file:

swagger: "2.0" info: version: 1.0.0 title: Simple API description: A simple API to learn how to write OpenAPI Specification schemes: - https host: simple.api basePath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. parameters: - name: pageSize in: query description: Number of persons returned type: integer - name: pageNumber in: query description: Page number type: integer responses: 200: description: A list of Person schema: $ref: "#/definitions/Persons" post: summary: Creates a person description: Adds a new person to the persons list. parameters: - name: person in: body description: The person to create. schema: $ref: "person.yaml#/Person" responses: 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. parameters: - name: username in: path required: true description: The person's username type: string responses: 200: description: A Person schema: $ref: "person.yaml#/Person" 404: description: The Person does not exists. definitions: Persons: type: array items: $ref: "person.yaml#/Person"

Editing splitted local files with the online editor

Tools will look for the referenced file (person.yaml) in the same directory as the file containing the reference. But when you use the online editor it does not make sense, such local reference cannot be resolved.

Fortunately the editor propose a configuration allowing to set a server to resolve these local references. This configuration is accessible in the Preferences->Preferences menu:

The Pointer Resolution Base Path configuration is on the bottom of the configuration screen:

All you need to do is put the referenced yaml files into a web server (with CORS activated) and modify the editor’s configuration to point this server.

http-server a lightweight web server

You can use http-server a lightweight node.js web server:

npm install --global http-server

You now can start a web service on any folder:

http-server --cors path/to/yaml/folder

cd path/to/yaml/folder http-server --cors .

By default, http-server listens on 8080 port, files will be accessble through http://localhost:8080/<path to file within folder>.

The --cors flag is used to activate CORS directive and allow XHR request to this local webserver from the online editor page. Without CORS activated, the editor will not be able to download files.

Modifying online editor configuration

Once the web server is started you can modifiy the editor to set the URL to http://localhost:8080/:

Files referenced with $ref: <filename>#/example will be downloaded from http://localhost:8080/<filename>.

Once this is done, you may need to do a force refresh (clean cache) of the editor’s the page to get the green bar.

Cache

When you add a reference to a new file (that was not already reference), this new file may not be downloaded automatically resulting in errors (Reference could not be resolved: newfile.yaml). You may need to refresh the editor’s page with cache cleaning to solve this error.

Folders

You’re under no obligation to put all sub-files on a “root” level, you can store them in differents sub-folders.

Reference to a file in a folder

Let’s move the person.yaml file into a sub-folder folder, the new reference will be like this:

 $ref: "folder/person.yaml#/Person"

File referencing a file from an upper folder

You can also reference a file outside the current folder. Let’s create a persons.yaml file into a another-folder folder:

Persons: type: array items: $ref: "../folder/person.yaml#/Person"

This file reference the person.yaml file using .. to get to the upper level.

To use persons.yaml, we proceed just like with person.yaml. We remove the Persons definition from the main file and we replace its reference #/definitions/Persons by another-folder/persons.yaml#Persons.

Here’s the full file with all definitions externalized (the definitions section has been removed):

swagger: "2.0" info: version: 1.0.0 title: Simple API description: A simple API to learn how to write OpenAPI Specification schemes: - https host: simple.api basePath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. parameters: - name: pageSize in: query description: Number of persons returned type: integer - name: pageNumber in: query description: Page number type: integer responses: 200: description: A list of Person schema: $ref: "another-folder/persons.yaml#/Persons" post: summary: Creates a person description: Adds a new person to the persons list. parameters: - name: person in: body description: The person to create. schema: $ref: "folder/person.yaml#/Person" responses: 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. parameters: - name: username in: path required: true description: The person's username type: string responses: 200: description: A Person schema: $ref: "folder/person.yaml#/Person" 404: description: The Person does not exists.

Referencing a remote files

As you may have guess while modifying the references in the specification and editor configuration, it is also possible to reference a remote file.

Remote files

All we need to do is to put the full file’s URL in the reference:

$ref: https://myserver.com/mypath/myfile.yaml#/example

Remember that the server MUST have CORS activated to allow the editor to download the file.

We have launched a web server on 8080 port, so all we have to do is add http://localhost:8080/ to the references to Person:

 $ref: "http://localhost:8080/folder/person.yaml#/Person"

Remote files containing local references

What happen if the remote file reference a local file? (Main file -> Remote file -> Local file).

The parser will seek this “local” file on the remote server providing the remote file.

If we replace the local to Persons by a remote reference…

 $ref: "http://localhost:8080/another-folder/persons.yaml#/Persons"

… the person.yaml file referenced “locally” in the persons.yaml file will be loaded from http://localhost:8080 which has served the persons.yaml.

Remote files containing remote references

If a remote file contains a remote reference (Main file -> Remote file -> Remote file ), it will be resolved like in 2.4.1 Remote files.

We can replace the person.yaml file local reference by a remote reference in persons.yaml:

Persons: type: array items: $ref: "http://localhost:8080/folder/person.yaml#/Person"

Multiple items in a single sub-file

We have put Person and Persons definitions in separate files: this is not an obligation. You can put more than one item in a single file, you only need to use the right JSON Pointer.

Person and Person in a single file

If we concatenate person.yaml and persons.yaml into a single file called definitions.yaml:

Person: required: - username properties: firstName: type: string lastName: type: string username: type: string Persons: type: array items: $ref: "#/Person"

Note that in Persons the reference to Person is now #/Person.

In the main file we only need to change the filename when reference these two definitions:

 $ref: "definitions.yaml#/Persons"

 $ref: "definitions.yaml#/Person"

Organizing content in a sub-file

Within the sub-file you can organize the content as you wish. Here Person is in SomeDefinitions and Persons is in OtherDefinitions:

SomeDefinitions: Person: required: - username properties: firstName: type: string lastName: type: string username: type: string OtherDefinitions: Persons: type: array items: $ref: "#/SomeDefinitions/Person"

Note that in Persons the reference to Person is now #/SomeDefinitions/Person.

In the main file we have to modify the path to get the item in the sub-file for these two definitions:

 $ref: "definitions.yaml#/OtherDefinitions/Persons"

 $ref: "definitions.yaml#/SomeDefinitions/Person"

Definitions, Responses, Parameters

What we have done with Person and Persons definitions can be done with any reusable items (i.e. using $ref) such as responses and parameters in the Open API Specification file.

OpenAPI chainsaw massacre

Thanks to Mohsen Azimi’s post I’ve discovered that using sub-files for definitions, responses and parameters which obviously use $ref JSON Pointers is not the only way of using sub-files. You can use sub-files for almost anything in the specification.

We will split the huge file created in previous post about documentation.

Let the chainsaw massacre begin

Let’s start with the info section:

swagger: '2.0' info: version: 1.1.0 title: Simple API description: | A simple API to learn how to write OpenAPI Specification. This file uses almost every single aspect of the [Open API Specification](https://openapis.org/). This API will use JSON. JSON looks like this: ```JSON { "key": "value", "anotherKey": "anotherValue" } ``` termsOfService: http://simple.api/terms-of-service contact: name: John Doe url: http://simple.api/contact email: [email protected] license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0

We can put its whole content in a file called info.yaml:

version: 1.1.0 title: Simple API description: | A simple API to learn how to write OpenAPI Specification. This file uses almost every single aspect of the [Open API Specification](https://openapis.org/). This API will use JSON. JSON looks like this: ```JSON { "key": "value", "anotherKey": "anotherValue" } ``` termsOfService: http://simple.api/terms-of-service contact: name: John Doe url: http://simple.api/contact email: [email protected] license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0

And reference it just like this in info:

swagger: '2.0' info: $ref: info.yaml

The wizard of resolution

We can do the same thing with paths, definitions, responses and parameters: copy the section content in a sub-file (paths.yaml, definitions.yaml, responses.yaml and parameters.yaml) and reference it in the main file:

paths: $ref: paths.yaml definitions: $ref: definitions.yaml responses: $ref: responses.yaml parameters: $ref: parameters.yaml

If you remember previous posts, these sections references each other in many ways, for example in paths.yaml:

'/persons/{username}': parameters: - $ref: '#/parameters/username'

The username parameter is no longer in the main file and is not in the paths.yaml file but in the parameters.yaml file:

username: name: username in: path required: true description: The person's username type: string

How could the main file be considered valid in the editor (or in any tool parsing the file)? It’s simply because the sub-files are loaded and then the whole content (file + sub-files) is validated.

A less rough split

We can use JSON pointers for almost anything in the specification as as long as the $ref JSON pointer reference something corresponding to the expected object (or value) in the OpenAPI specification.

Referencing object in custom structure

And as seen earlier in this post we can put many items in a sub-file.

The documentation.yaml file contains the data for externalDocs and tags (note the custom structure on line 1 and 6):

external: description: | **Complete** documentation describing how to use this API url: http://doc.simple.api/ categories: - name: Persons description: Everything you need to handle `users` and `friends` externalDocs: description: People category documentation url: http://doc.simple.api/people - name: Items description: Everything you need to handle items collected by users externalDocs: description: Items category documentation url: http://doc.simple.api/items - name: Media description: Everything you need to handle images externalDocs: description: Media category documentation url: http://doc.simple.api/media - name: JSLess description: Specific operations for JS less consumers externalDocs: description: JS Less Consumers documentation url: http://doc.simple.api/jsless

These data are referenced this way in the main file:

externalDocs: $ref: documentation.yaml#/external tags: $ref: documentation.yaml#/categories

The security.yaml file contains the data for securityDefinitions and security (note the custom structure on line 20):

securityDefinitions: OauthSecurity: description: New Oauth security system. Do not use MediaSecurity or LegacySecurity. type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: admin: Admin scope user: User scope MediaSecurity: description: Specific media security for backward compatibility. Use OauthSecurity instead. type: apiKey in: query name: media-api-key LegacySecurity: description: Legacy security system for backward compatibility. Use OauthSecurity instead. type: basic defaultSecurity: - OauthSecurity: - user - LegacySecurity: []

Referencing a string or a simple list

It also work for simpler value like a string or a list of string. The schema, host and basepath values can be moved into a single file security.yaml (note the custom structure on line 3 and 4):

schemes: - https server_and_port: simple.api path: /openapi102

And referenced like this

schemes: $ref: endpoint.yaml#/schemes host: $ref: endpoint.yaml#/server_and_port basePath: $ref: endpoint.yaml#/path

Reusing a value

As long as the API consumes and produces the same media types, we define a single value in the mediatypes.yaml file:

default: - application/json - application/x-yaml

And then we reference this single value in both produces and consumes:

consumes: $ref: mediatypes.yaml#/default produces: $ref: mediatypes.yaml#/default

A smarter split

The API we built with the previous parts could be divided in four parts:

Common items like headers, media types, security, definitions, parameters and responses
Persons operations, parameters, responses and definitions
Legacy operations
Images operations

We can create 4 sub-files and reference them from a main file.

commons.yaml

In the commons.yaml file we put every items that can be reused across other files:

securityDefinitions: OauthSecurity: description: New Oauth security system. Do not use MediaSecurity or LegacySecurity. type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: admin: Admin scope user: User scope MediaSecurity: description: Specific media security for backward compatibility. Use OauthSecurity instead. type: apiKey in: query name: media-api-key LegacySecurity: description: Legacy security system for backward compatibility. Use OauthSecurity instead. type: basic defaultSecurity: - OauthSecurity: - user - LegacySecurity: [] defaultMediatypes: - application/json - application/x-yaml defaultHeaders: X-Rate-Limit-Remaining: description: How many calls consumer can do type: integer X-Rate-Limit-Reset: description: When rate limit will be reset type: string format: date-time parameters: userAgent: name: User-Agent description: All API consumers MUST provide a user agent type: string in: header required: true pageSize: name: pageSize in: query description: Number of items returned type: integer format: int32 minimum: 0 exclusiveMinimum: true maximum: 100 exclusiveMaximum: false multipleOf: 10 default: 20 pageNumber: name: pageNumber in: query description: Page number type: integer default: 1 responses: Standard500ErrorResponse: description: An unexpected error occured. headers: $ref: '#/defaultHeaders' schema: $ref: '#/definitions/Error' TotallyUnexpectedResponse: description: A totally unexpected response headers: $ref: '#/defaultHeaders' definitions: ErrorMessage: title: MultiDeviceErrorMessage description: An error message with a long and a short description required: - longMessage - shortMessage properties: longMessage: description: A long error description type: string shortMessage: description: A short error description type: string MultilingualErrorMessage: title: MultiLingualMultiDeviceErrorMessage description: An multilingual error message (hashmap) with a long and a short description additionalProperties: $ref: '#/definitions/ErrorMessage' properties: defaultLanguage: $ref: '#/definitions/ErrorMessage' example: defaultLanguage: longMessage: We're deeply sorry but an error occured shortMessage: Error fr: longMessage: Nous sommes désolé mais une erreur est survenu shortMessage: Erreur Error: title: MultiLingualMultiDeviceError description: Give full information about the problem required: - code - message properties: code: description: A human readable code (death to numeric error codes!) type: string enum: - DBERR - NTERR - UNERR example: UNERR message: $ref: '#/definitions/MultilingualErrorMessage' Paging: required: - totalItems - totalPages - pageSize - currentPage properties: totalItems: type: integer totalPages: type: integer pageSize: type: integer currentPage: type: integer

images.yaml

In the images.yaml file we put both /images and /images/{id} paths informations:

 images: parameters: - $ref: 'commons.yaml#/parameters/userAgent' post: summary: Uploads an image description: Upload an image, will return an image id. operationId: storeImage externalDocs: description: How to upload media url: http://doc.simple.api/media/upload tags: - Media security: - MediaSecurity: [] consumes: - multipart/form-data parameters: - name: image in: formData type: file responses: '200': description: Image's ID schema: properties: imageId: type: string headers: $ref: commons.yaml#/defaultHeaders '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' images-imageId: parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets an image description: Return an image operationId: readImage tags: - Media parameters: - name: imageId in: path required: true type: string produces: - image/png - image/gif - image/jpeg - application/json - application/x-yaml responses: '200': description: The image headers: $ref: commons.yaml#/defaultHeaders '404': description: Image do not exists headers: $ref: commons.yaml#/defaultHeaders '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse'

Note that all references to common items point to commons.yaml.

legacy.yaml

Same for the /js-less-consumer-persons path we put in legacy.yaml file in js-less-consumer-persons:

js-less-consumer-persons: parameters: - $ref: 'commons.yaml#/parameters/userAgent' post: summary: Creates a person description: For JS-less partners operationId: createUserJS deprecated: true tags: - JSLess - Persons security: - OauthSecurity: - admin - LegacySecurity: [] consumes: - application/x-www-form-urlencoded produces: - text/html parameters: - name: username in: formData required: true pattern: '[a-z0-9]{8,64}' minLength: 8 maxLength: 64 type: string - name: firstname in: formData type: string - name: lastname in: formData type: string - name: dateOfBirth in: formData type: string format: date responses: '204': description: Person succesfully created. headers: $ref: 'commons.yaml#/defaultHeaders' '400': description: Person couldn't have been created. headers: $ref: 'commons.yaml#/defaultHeaders' '500': description: An error occured. headers: $ref: 'commons.yaml#/defaultHeaders' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse'

persons.yaml

All persons items go in the persons.yaml:

each path go in its own named section (like persons-username for /persons/{username})
all persons specific definitions goes in definitions (and can be referenced with #definition/name)
all persons specific responses goes in responses (and can be referenced with #responses/name)
all persons specific parameters goes in parameters (and can be referenced with #parameters/name)

persons: parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. operationId: searchUsers tags: - Persons parameters: - $ref: 'commons.yaml#/parameters/pageSize' - $ref: 'commons.yaml#/parameters/pageNumber' - $ref: '#/parameters/includeNonVerifiedUsers' - $ref: '#/parameters/sortPersons' responses: '200': description: A list of Person schema: $ref: '#/definitions/Persons' headers: $ref: commons.yaml#/defaultHeaders '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' post: summary: Creates a person description: Adds a new person to the persons list. operationId: createUser tags: - Persons security: - OauthSecurity: - admin - LegacySecurity: [] parameters: - name: person in: body required: true description: The person to create. schema: $ref: '#/definitions/Person' responses: '204': description: Person succesfully created. headers: $ref: commons.yaml#/defaultHeaders '400': description: Person couldn't have been created. headers: $ref: commons.yaml#/defaultHeaders '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' persons-username: parameters: - $ref: '#/parameters/username' - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets a person description: Returns a single person for its username. operationId: readPerson tags: - Persons responses: '200': description: A Person schema: $ref: '#/definitions/Person' headers: $ref: commons.yaml#/defaultHeaders '404': $ref: '#/responses/PersonDoesNotExistResponse' '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' delete: summary: Deletes a person description: Delete a single person identified via its username operationId: deletePerson tags: - Persons responses: '204': description: Person successfully deleted. headers: $ref: commons.yaml#/defaultHeaders '404': $ref: '#/responses/PersonDoesNotExistResponse' '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' persons-username-friends: parameters: - $ref: '#/parameters/username' - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets a person's friends description: Returns a list containing all persons. The list supports paging. operationId: readPersonsFriends tags: - Persons parameters: - $ref: 'commons.yaml#/parameters/pageSize' - $ref: 'commons.yaml#/parameters/pageNumber' - $ref: '#/parameters/includeNonVerifiedUsers' - $ref: '#/parameters/sortPersons' responses: '200': description: A person's friends list schema: $ref: '#/definitions/PagedPersons' headers: $ref: commons.yaml#/defaultHeaders '404': $ref: '#/responses/PersonDoesNotExistResponse' '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' persons-username-collecting-items: parameters: - $ref: '#/parameters/username' - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets a person's collecting items list description: | Returns a list containing all items this person is looking for. The list supports paging. operationId: readPersonsCollectingItems tags: - Items parameters: - $ref: 'commons.yaml#/parameters/pageSize' - $ref: 'commons.yaml#/parameters/pageNumber' - $ref: '#/parameters/filterItemTypes' responses: '200': description: A collected items list schema: $ref: '#/definitions/PagedCollectingItems' headers: $ref: commons.yaml#/defaultHeaders examples: application/json: { "totalItems": 10, "totalPage": 4, "pageSize": 3, "currentPage": 2, "items": [ { "itemType": "Vinyl", "maxPrice": 20, "imageId": "98096838-04eb-4bac-b32e-cd5b7196de71", "albumName": "Captain Future Original Soundtrack", "artist": "Yuji Ohno" }, { "itemType": "VHS", "maxPrice": 10, "imageId": "b74469bc-e6a1-4a90-858a-88ef94079356", "movieTitle": "Star Crash", "director": "Luigi Cozzi" }, { "itemType": "AudioCassette", "maxPrice": 10, "imageId": "b74469bc-e6a1-4a90-858a-88ef94079356", "albumName": "Star Wars", "artist": "John Williams" } ] } '404': $ref: '#/responses/PersonDoesNotExistResponse' '500': $ref: 'commons.yaml#/responses/Standard500ErrorResponse' default: $ref: 'commons.yaml#/responses/TotallyUnexpectedResponse' definitions: Person: title: Human description: A person which can be the user itself or one of his friend required: - username properties: firstName: description: first name type: string example: John lastName: description: last name type: string example: Doe username: description: Username used to connect to the service type: string pattern: '[a-z0-9]{8,64}' minLength: 8 maxLength: 64 example: john1doe6 dateOfBirth: description: Date of birth type: string format: date example: 1978-06-21 lastTimeOnline: description: The last time this person was connected to the service as a type: string format: date-time readOnly: true example: 2016-06-10T12:36:58.014Z avatarBase64PNG: description: An avatar PNG image as a base64 encoded string ready to use as an src in img html tag type: string format: byte default: data:image/png;base64,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 spokenLanguages: $ref: '#/definitions/SpokenLanguages' SpokenLanguages: title: Languages description: A hashmap of spoken languages additionalProperties: description: An additional spoken language type: string properties: defaultLanguage: description: Default spoken language type: string default: english example: defaultLanguage: french it: italian fr: french Persons: title: Humans description: A list of users or friends required: - items properties: items: description: Array containg the list type: array minItems: 10 maxItems: 100 uniqueItems: true items: $ref: '#/definitions/Person' example: - firstname: Robert lastname": Doe username": robdo dateOfBirth: 1970-01-28 lastTimeOnline: 2016-04-10T14:36:58.014Z - firstname: Jane lastname: Doe username: jdoe123 dateOfBirth: 1980-05-12 lastTimeOnline: 2016-05-12T19:23:59.014Z CollectingItem: discriminator: itemType required: - itemType properties: itemType: description: | An item can be of different type: type | definition -----|----------- Vinyl| #/definitions/Vinyl VHS | #/definitions/VHS AudioCassette | #/definitions/AudioCassette type: string enum: - AudioCassette - Vinyl - VHS imageId: type: string maxPrice: type: number format: double minimum: 0 maximum: 10000 exclusiveMinimum: true exclusiveMaximum: false Vinyl: allOf: - $ref: '#/definitions/CollectingItem' - required: - albumName - artist properties: albumName: type: string artist: type: string VHS: allOf: - $ref: '#/definitions/CollectingItem' - required: - movieTitle properties: movieTitle: type: string director: type: string AudioCassette: allOf: - $ref: '#/definitions/CollectingItem' - required: - albumName - artist properties: albumName: type: string artist: type: string PagedPersons: allOf: - $ref: '#/definitions/Persons' - $ref: 'commons.yaml#/definitions/Paging' PagedCollectingItems: allOf: - properties: items: type: array minItems: 10 maxItems: 100 uniqueItems: true items: $ref: '#/definitions/CollectingItem' - $ref: 'commons.yaml#/definitions/Paging' responses: PersonDoesNotExistResponse: description: Person does not exist. headers: $ref: commons.yaml#/defaultHeaders parameters: username: name: username in: path required: true description: The person's username type: string includeNonVerifiedUsers: name: includeNonVerifiedUsers in: query description: Result will not include non verified user by default if this parameter is not provided type: boolean default: false allowEmptyValue: true sortPersons: name: sort in: query description: Result will be sorted by lastTimeOnline descending and username ascending by default if this parameter is not provided type: array uniqueItems: true minItems: 1 maxItems: 3 collectionFormat: pipes items: type: string pattern: '[-+](username|lastTimeOnline|firstname|lastname)' default: - -lastTimeOnline - +username filterItemTypes: name: itemType in: query description: Filter collected items on their type type: array collectionFormat: multi uniqueItems: true items: type: string enum: - AudioCassette - Vinyl - VHS

full main file

Here’s the full main file where we reference the 4 sub-files:

swagger: '2.0' info: version: 1.1.0 title: Simple API description: | A simple API to learn how to write OpenAPI Specification. This file uses almost every single aspect of the [Open API Specification](https://openapis.org/). This API will use JSON. JSON looks like this: ```JSON { "key": "value", "anotherKey": "anotherValue" } ``` termsOfService: http://simple.api/terms-of-service contact: name: John Doe url: http://simple.api/contact email: [email protected] license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0 externalDocs: description: | **Complete** documentation describing how to use this API url: http://doc.simple.api/ tags: - name: Persons description: Everything you need to handle `users` and `friends` externalDocs: description: People category documentation url: http://doc.simple.api/people - name: Items description: Everything you need to handle items collected by users externalDocs: description: Items category documentation url: http://doc.simple.api/items - name: Media description: Everything you need to handle images externalDocs: description: Media category documentation url: http://doc.simple.api/media - name: JSLess description: Specific operations for JS less consumers externalDocs: description: JS Less Consumers documentation url: http://doc.simple.api/jsless schemes: - https host: simple.api basePath: /openapi101 consumes: $ref: commons.yaml#/defaultMediatypes produces: $ref: commons.yaml#/defaultMediatypes securityDefinitions: $ref: commons.yaml#/securityDefinitions security: $ref: commons.yaml#/defaultSecurity paths: /persons: $ref: 'persons.yaml#/persons' /js-less-consumer-persons: $ref: 'legacy.yaml#/js-less-consumer-persons' '/persons/{username}': $ref: 'persons.yaml#/persons-username' '/persons/{username}/friends': $ref: 'persons.yaml#/persons-username-friends' '/persons/{username}/collecting-items': $ref: 'persons.yaml#/persons-username-collecting-items' /images: $ref: 'images.yaml#/images' /images/{imageId}: $ref: 'images.yaml#/images-imageId'

Valid sub-files

If we put the last persons.yaml file content in the editor, it ends with these errors:

Splitting a huge Open API Specification file to keep it maintainable is a great idea but if you cannot validate sub-files against the specification, you gain almost nothing.

Making commons.yaml valid

If we put the commons.yaml file created earlier in the editor we get these errors:

Missing required property: swagger
Missing required property: info
Missing required property: paths
Additional properties not allowed: defaultHeaders,defaultMediatypes,defaultSecurity

Let’s see how we can fix these errors.

Missing swagger property

We just need to add this line on file’s top:

swagger: "2.0"

Missing info property

We add an short info section after swagger:

info: version: 1.0.0 title: Common elements description: Shared elements in all API

Missing paths property

As we do not define any path in this file we just need to add an empty paths section:

paths: {}

Property defaultSecurity not allowed

As the defaultSecurity correspond to the OpenAPI security section we just need to rename it:

Invalid commons.yaml file:

defaultSecurity: - OauthSecurity: - user - LegacySecurity: []

Valid commons.yaml file:

security: - OauthSecurity: - user - LegacySecurity: []

Property defaultMediatypes not allowed

defaultMediaType is not a valid OpenAPI property:

defaultMediatypes: - application/json - application/x-yaml

We will use produces and consumes to define the default media types. But as we want to define a single set of media type we will use this trick:

produces: - application/json - application/x-yaml consumes: $ref: '#/produces'

In the future if we want to define different sets of media types for produces and consumes, we’ll be ready.

Property defaultHeaders not allowed

defaultHeaders is not a valid OpenAPI property:

defaultHeaders: X-Rate-Limit-Remaining: description: How many calls consumer can do type: integer X-Rate-Limit-Reset: description: When rate limit will be reset type: string format: date-time

We will use a dummy response definition DefaultHeaders to declare these default headers:

responses: DefaultHeaders: description: A dummy response to define default header headers: X-Rate-Limit-Remaining: description: How many calls consumer can do type: integer X-Rate-Limit-Reset: description: When rate limit will be reset type: string format: date-time

Of course we need to update common responses to use these headers:

 Standard500ErrorResponse: description: An unexpected error occured. headers: $ref: '#/responses/DefaultHeaders/headers' schema: $ref: '#/definitions/Error' TotallyUnexpectedResponse: description: A totally unexpected response headers: $ref: '#/responses/DefaultHeaders/headers'

Making persons.yaml valid

Just like with commons.yaml, if we put persons.yaml content in the editor we get some errors:

Missing required property: swagger
Missing required property: info
Reference could not be resolved: commons.yaml#/defaultHeaders
Missing required property: paths
Additional properties not allowed: persons-username-collecting-items,persons-username-friends,persons-username,persons

Missing swagger and info properties

We just add swagger and info like for commons.yaml:

swagger: "2.0" info: version: 1.0.0 title: Persons Sub-API description: Persons operations, definitions, parameters and responses securityDefinitions: $ref: commons.yaml#/securityDefinitions

commons.yaml#/defaultHeaders reference could not be resolved

As the commons.yaml structure has been modified concerning default headers we need to replace these references:

 $ref: commons.yaml#/defaultHeaders

by this one:

 $ref: 'commons.yaml#/responses/DefaultHeaders/headers'

Missing paths and additional properties not allowed

We have defined custom properties for each path relative to persons operations, therefore there is no paths section and our custom properties (like persons) are not allowed by the OpenAPI specification.

persons: parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. operationId: searchUsers

We need to add a paths section and put all our path in it using the correct path value as key:

paths: '/persons': parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. operationId: searchUsers

New errors: Security definition could not be resolved

Once this is done, 2 new errors appear:

Security definition could not be resolved: OauthSecurity
Security definition could not be resolved: LegacySecurity

Now that we have a valid structure, the paths have been parsed and the parser detected missing security definitions. To solve this error, we add these definitions by referencing the commons.yaml file:

securityDefinitions: $ref: commons.yaml#/securityDefinitions

images.yaml and legacy.yaml

For images.yaml and legacy.yaml we do exactly the same things as we’ve done with persons.yaml.

Here the images.yaml file modified (partial view):

swagger: "2.0" info: version: 1.0.0 title: Images Sub-API description: images operations securityDefinitions: $ref: commons.yaml#/securityDefinitions paths: /images:

Here the legacy.yaml file modified (partial view):

swagger: "2.0" info: version: 1.0.0 title: Legacy Sub-API description: Legacy operations securityDefinitions: $ref: commons.yaml#/securityDefinitions paths: /js-less-consumer-persons:

Updating the main file

Now that we have modified all sub-files, if we try to edit the main file we get these errors

Reference could not be resolved: commons.yaml#/defaultMediatypes
Reference could not be resolved: commons.yaml#/defaultSecurity
Reference could not be resolved: persons.yaml#/persons
Reference could not be resolved: images.yaml#/images-imageId
Reference could not be resolved: persons.yaml#/persons-username
Reference could not be resolved: persons.yaml#/persons-username-friends
Reference could not be resolved: persons.yaml#/persons-username-collecting-items
Reference could not be resolved: images.yaml#/images
Reference could not be resolved: legacy.yaml#/js-less-consumer-persons

These errors are of 2 types:

those due to the commons.yaml structure modification
and those due to the persons.yaml, images.yaml and legacy.yaml paths structure modifications

Modifiying commons.yaml references

Before:

consumes: $ref: commons.yaml#/defaultMediatypes produces: $ref: commons.yaml#/defaultMediatypes securityDefinitions: $ref: commons.yaml#/securityDefinitions security: $ref: commons.yaml#/defaultSecurity

After:

consumes: $ref: 'commons.yaml#/consumes' produces: $ref: 'commons.yaml#/produces' securityDefinitions: $ref: 'commons.yaml#/securityDefinitions' security: $ref: 'commons.yaml#/security'

Modifying paths references

This is the trickyest part of this tutorial. To reference the /persons path in persons.yaml we used persons.yaml#/persons:

paths: /persons: $ref: 'persons.yaml#/persons'

But persons.yaml structure has changed from :

persons: parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. operationId: searchUsers

to:

paths: '/persons': parameters: - $ref: 'commons.yaml#/parameters/userAgent' get: summary: Gets some persons description: Returns a list containing all persons. The list supports paging. operationId: searchUsers

The new reference should be something like persons.yaml#/paths//persons but if we try it, the editor shows an error Reference could not be resolved: persons.yaml#/paths//persons. The / in /persons needs to be escaped, how can we do that?

Evaluation of each reference token begins by decoding any escaped character sequence. This is performed by first transforming any occurrence of the sequence ‘~1’ to ‘/’ RFC6901

Before modification:

paths: /persons: $ref: 'persons.yaml#/persons' /js-less-consumer-persons: $ref: 'legacy.yaml#/js-less-consumer-persons' '/persons/{username}': $ref: 'persons.yaml#/persons-username' '/persons/{username}/friends': $ref: 'persons.yaml#/persons-username-friends' '/persons/{username}/collecting-items': $ref: 'persons.yaml#/persons-username-collecting-items' /images: $ref: 'images.yaml#/images' /images/{imageId}: $ref: 'images.yaml#/images-imageId'

After modification (all / in reference name have been replaced by ~1):

paths: /persons: $ref: 'persons.yaml#/paths/~1persons' /js-less-consumer-persons: $ref: 'legacy.yaml#/paths/~1js-less-consumer-persons' '/persons/{username}': $ref: 'persons.yaml#/paths/~1persons~1{username}' '/persons/{username}/friends': $ref: 'persons.yaml#/paths/~1persons~1{username}~1friends' '/persons/{username}/collecting-items': $ref: 'persons.yaml#/paths/~1persons~1{username}~1collecting-items' /images: $ref: 'images.yaml#/paths/~1images' /images/{imageId}: $ref: 'images.yaml#/paths/~1images~1{imageId}'

And now the main file and all its sub-files are considered valid by the editor.

Conclusion

You are now ready to split any OpenAPI specification file into valid sub-files in any possible ways. In this 8th part you’ve learned how to use JSON pointers in almost any places in an OpenAPI specification to references items from other files and how to create valid sub-files containing partial information. In the next final part (at last) we will learn how to extend the OpenAPI specification.