{"id":20770648,"url":"https://github.com/hackolade/swagger","last_synced_at":"2025-10-24T21:18:40.967Z","repository":{"id":43176691,"uuid":"176828668","full_name":"hackolade/Swagger","owner":"hackolade","description":"Hackolade(https://hackolade.com) plugin for Swagger 2 API documentation","archived":false,"fork":false,"pushed_at":"2025-03-14T17:29:51.000Z","size":4828,"stargazers_count":1,"open_issues_count":1,"forks_count":11,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-03-30T16:46:26.479Z","etag":null,"topics":["api-management","data-modeling","model-driven","schema-design","swagger","swagger-documentation"],"latest_commit_sha":null,"homepage":"https://github.com/hackolade/Swagger/releases/latest","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hackolade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-20T22:47:45.000Z","updated_at":"2025-03-14T17:29:54.000Z","dependencies_parsed_at":"2023-12-12T16:50:42.663Z","dependency_job_id":"7f030a52-820a-4b97-a2a3-38e3174be5ac","html_url":"https://github.com/hackolade/Swagger","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackolade%2FSwagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackolade%2FSwagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackolade%2FSwagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackolade%2FSwagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hackolade","download_url":"https://codeload.github.com/hackolade/Swagger/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251714939,"owners_count":21631806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-management","data-modeling","model-driven","schema-design","swagger","swagger-documentation"],"created_at":"2024-11-17T12:11:06.638Z","updated_at":"2025-10-24T21:18:40.876Z","avatar_url":"https://github.com/hackolade.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger\nPlugin to enable Swagger 2 as a target in Hackolade data modeling.  Requires prior download of the Hackolade application from our [download page](https://hackolade.com/download.html)\n\nThis plugin is for Swagger 2 only.  If instead you need OpenAPI 3, you need a separate plugin accessible [here](https://github.com/hackolade/OpenAPI).\n\n\u003cspan class=\"rvts6\"\u003eThe goal of Swagger is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.  When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.  Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eTechnically speaking - Swagger is a\u003c/span\u003e [formal specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) \u003cspan class=\"rvts6\"\u003esurrounded by a large ecosystem of tools, which includes everything from front-end user interfaces, low-level code libraries and commercial API management solutions.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eTo perform model-first design of a REST API using Swagger with Hackolade, you must first download the Swagger\u003c/span\u003e [plugin](https://hackolade.com/help/DownloadadditionalDBtargetplugin.html)\u003cspan class=\"rvts6\"\u003e.  This plugin is strictly compliant with version 2.0 of the OpenAPI specification.  Another plugin is required to support the OpenAPI 3.0 specification.\u003c/span\u003e\n\n\u003cspan class=\"rvts21\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts21\"\u003eCreating APIs is not easy! And writing Swagger documentation in a design-first approach can be tedious at best, generally error-prone and frustrating...  Hackolade takes a visual schema-centric approach so you can focus on the content of requests and responses. The application also assists with all the metadata to produce validated Swagger files and test the transactions.  You can also reverse-engineer existing Swagger files in JSON or YAML to produce a graphical representation of your APIs.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eHackolade was specially adapted to support the API design of Swagger, including all the necessary metadata for the API, the requests and responses.  The application closely follows the terminology of the specification.  The visual tool puts the focus on what really matters in an API: the schema of the information being exchanged between systems.  At the same time, it provides assistance to modelers and does not require perfect mastery of the Swagger syntax.  It generates validated files that are syntactically correct and compatible with the specification thereby greatly improving productivity and quality.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThe diagram below results from the reverse-engineering of the\u003c/span\u003e [Pet Store](https://mermade.org.uk/examples/swagger.json) \u003cspan class=\"rvts6\"\u003esample API.\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Workspace.png\" width=\"100%\" height=\"100%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eData Types\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThe Swagger specification describes primitives (or scalar) data types which can have an optional property modifier,\u003c/span\u003e \u003cspan class=\"rvts69\"\u003eformat\u003c/span\u003e\u003cspan class=\"rvts6\"\u003e, plus a file primitive type.  Complex types such as arrays and sub-objects, plus combinations thereof, are also allowed.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger data types.png\" width=\"25%\" height=\"25%\"\u003e\u003cimg src=\"lib/Swagger data types - string.png\" width=\"25%\" height=\"25%\"\u003e\u003cimg src=\"lib/Swagger data types - number.png\" width=\"25%\" height=\"25%\"\u003e\u003cimg src=\"lib/Swagger data types - integer.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eAPI metadata\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThe info object, as well as the host, basePath, schemes, consumes, produces, the securityDefinitions object, the security object, the tags object, and externalDocs object are fixed fields treated as metadata and maintained at model-level in Hackolade.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e\u003c/span\u003e\n\u003cimg src=\"lib/Swagger - Info object 1.png\" width=\"33%\" height=\"33%\"\u003e\u003cimg src=\"lib/Swagger - Info object 2.png\" width=\"33%\" height=\"33%\"\u003e\n\u003cimg src=\"lib/Swagger - Info object 3.png\" width=\"33%\" height=\"33%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eDefinitions\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003eAn object of\u003c/span\u003e [schema objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schema-object) \u003cspan class=\"rvts34\"\u003ewith definitions of inputs and outputs to be produced and consumed by operations.  Data types can be objects, but also primitives and arrays. This object is based on the\u003c/span\u003e[JSON Schema Specification Draft 4](http://json-schema.org/)\u003cspan class=\"rvts34\"\u003e and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003e  \n\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Definitions.png\" width=\"66%\" height=\"66%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eConsult\u003c/span\u003e [this page](Reusableobjectsdefinitions.html) \u003cspan class=\"rvts6\"\u003eor more information on how to use definitions.  For Swagger, you should limit yourself to Hackolade model definitions.\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eResource\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThe resource path object is a container representing the relative path to an individual endpoint.  The field name must start with a slash (\"/\").  The path is appended to the basePath in order to construct the full URL.  Path templating (\u003c/span\u003e\u003cspan class=\"rvts34\"\u003eusage of curly braces (\"{}\") to mark a section of a URL path as replaceable using path parameters\u003c/span\u003e\u003cspan class=\"rvts6\"\u003e) is allowed.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eEach resource contains one or more \"\u003c/span\u003e[path item objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#path-item-object)\u003cspan class=\"rvts6\"\u003e\" made of a request and one or more responses:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Resource container.png\" width=\"100%\" height=\"100%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eYou may create a new resource via right-click anywhere in the ERD view and choosing the contextual menu option:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add resource contextual menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eor via the menu:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add resource action menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eor the toolbar:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add resource toolbar button.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eRequests\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eA request is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it.  Only a few standard methods are defined for the resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods\u003c/span\u003e\u003cspan class=\"rvts44\"\u003e.\u003c/span\u003e\u003cspan class=\"rvts6\"\u003e)\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThe\u003c/span\u003e [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object) \u003cspan class=\"rvts6\"\u003ed\u003c/span\u003e\u003cspan class=\"rvts74\"\u003eescribes a single operation parameter defined by a combination of a \u003c/span\u003e\u003cspan class=\"rvts21\"\u003ename\u003c/span\u003e\u003cspan class=\"rvts74\"\u003e and \u003c/span\u003e\u003cspan class=\"rvts21\"\u003elocation\u003c/span\u003e\u003cspan class=\"rvts74\"\u003e.  Hackolade provides a handy template of parameter types allowing the description of the payload either by adding adding individual fields or by referencing an existing definition.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Request parameter 1.png\" width=\"75%\" height=\"75%\"\u003e\n\u003cimg src=\"lib/Swagger - Request parameter 2.png\" width=\"75%\" height=\"75%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eTo create a request within a resource container, you may:\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e- right-click inside the container area of the ERD pane, and choose the contextual menu option:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add request contextual menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e- choose the Action menu:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add request action menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e- choose the toolbar button:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add request toolbar button.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eIt is easy to maintain the metadata for a request in the properties pane:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Request properties.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eResponses\u003c/span\u003e\u003c/span\u003e\n\n[Response definitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#response-object) \u003cspan class=\"rvts34\"\u003edescribe responses from API operations.  For each request, you may create one or more responses.\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003e  \n\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Request-Responses.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts34\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003eA response may have a schema that is defined as individual fields or references a definition:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Response schema.png\" width=\"75%\" height=\"75%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eTo create a response for a given request, you may:\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e- right-click on the request in the ERD and choose the contextual menu option:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add response contextual menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e- or choose the Action menu:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add response action menu.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e- or choose the toolbar button:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Add response toolbar button.png\" width=\"25%\" height=\"25%\"\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eIt is easy to maintain the metadata for a response in the properties pane:\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Response properties.png\" width=\"25%\" height=\"25%\"\u003e\n\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eForward-Engineering\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003eThe files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards.  Hackolade generates Swagger documentation in JSON format or YAML format.  The schema exposes two types of fields. Fixed fields, which have a declared name, and patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.  The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the \u003c/span\u003e[JSON Schema](http://json-schema.org/) [](http://json-schema.org/) \u003cspan class=\"rvts34\"\u003edefinitions.\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n\u003cimg src=\"lib/Swagger - Forward-Engineering.png\" width=\"100%\" height=\"100%\"\u003e\n\n\u003cspan class=\"rvts34\"\u003e  \n\u003c/span\u003e\n\n\u003cspan class=\"rvts34\"\u003eAn internal Swagger syntax validator ensures that the generated file is valid, and the right-hand pane allows interactions with the API and testing.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e\n\n## \u003cspan class=\"rvts0\"\u003e\u003cspan class=\"rvts15\"\u003eReverse-Engineering\u003c/span\u003e\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003eThis function lets you take a Swagger file in JSON or YAML format and generate a Hackolade model.  Then, you may enrich the model with comments, generate standard Hackolade documentation, and make the API evolve to generate a new Swagger file through forward-engineering.\u003c/span\u003e\n\n\u003cspan class=\"rvts6\"\u003e  \n\u003c/span\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackolade%2Fswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackolade%2Fswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackolade%2Fswagger/lists"}