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" 500: description: An unexpected error occured. schema: properties: code: type: string message: type: string 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. 500: description: An unexpected error occured. schema: properties: code: type: string message: type: string /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. 500: description: An unexpected error occured. schema: properties: code: type: string message: type: string definitions: Person: required: - username properties: firstName: type: string lastName: type: string username: type: string Persons: type: array items: $ref: "#/definitions/Person"