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: "http://localhost:8080/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: "http://localhost:8080/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: "http://localhost:8080/folder/person.yaml#/Person" 404: description: The Person does not exists.