{"id":15600507,"url":"https://github.com/jason-fox/fox.jason.passthrough.swagger","last_synced_at":"2025-04-19T19:50:29.160Z","repository":{"id":54521572,"uuid":"198161401","full_name":"jason-fox/fox.jason.passthrough.swagger","owner":"jason-fox","description":"Generate DITA-based REST API documentation from a Swagger file added directly to a ditamap","archived":false,"fork":false,"pushed_at":"2024-02-18T07:37:02.000Z","size":24149,"stargazers_count":5,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T12:26:50.988Z","etag":null,"topics":["dita","dita-ot-plugin","rest-api","swagger","swagger-documentation"],"latest_commit_sha":null,"homepage":"https://jason-fox.github.io/dita-ot-plugins/swagger","language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jason-fox.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-07-22T06:30:26.000Z","updated_at":"2025-01-29T16:50:07.000Z","dependencies_parsed_at":"2025-03-29T12:37:23.988Z","dependency_job_id":null,"html_url":"https://github.com/jason-fox/fox.jason.passthrough.swagger","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.passthrough.swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.passthrough.swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.passthrough.swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.passthrough.swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jason-fox","download_url":"https://codeload.github.com/jason-fox/fox.jason.passthrough.swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249785855,"owners_count":21325548,"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":["dita","dita-ot-plugin","rest-api","swagger","swagger-documentation"],"created_at":"2024-10-03T02:03:51.493Z","updated_at":"2025-04-19T19:50:29.133Z","avatar_url":"https://github.com/jason-fox.png","language":"XSLT","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger Plugin for DITA-OT [\u003cimg src=\"https://jason-fox.github.io/fox.jason.passthrough.swagger/swagger.png\" align=\"right\" width=\"300\"\u003e](http://swaggerdita-ot.rtfd.io/)\n\n[![license](https://img.shields.io/github/license/jason-fox/fox.jason.passthrough.swagger.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![DITA-OT 4.2](https://img.shields.io/badge/DITA--OT-4.2-green.svg)](http://www.dita-ot.org/4.2)\n[![CI](https://github.com/jason-fox/fox.jason.passthrough.swagger/workflows/CI/badge.svg)](https://github.com/jason-fox/fox.jason.passthrough.swagger/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/jason-fox/fox.jason.passthrough.swagger/badge.svg?branch=master)](https://coveralls.io/github/jason-fox/fox.jason.passthrough.swagger?branch=master)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=fox.jason.passthrough.swagger\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=fox.jason.passthrough.swagger)\n\nThis is a [DITA-OT Plug-in](https://www.dita-ot.org/plugins) used to auto-create valid DITA-based REST API\ndocumentation. The documentation can be generated directly from a [Swagger](https://github.com/swagger-api) file and\nprocessed as if it had been written in DITA.\n\n:arrow_forward: [Video from DITA-OT Day 2019](https://youtu.be/cd7XThpkivw)\n\n[![](https://jason-fox.github.io/fox.jason.passthrough.swagger/nothing-video.png)](https://youtu.be/cd7XThpkivw)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/summary\u003e\n\n-   [Background](#background)\n-   [Install](#install)\n    -   [Installing DITA-OT](#installing-dita-ot)\n    -   [Installing the Plug-in](#installing-the-plug-in)\n    -   [Installing Pandoc](#installing-pandoc)\n-   [Usage](#usage)\n-   [License](#license)\n\n\u003c/details\u003e\n\n## Background\n\n[\u003cimg src=\"https://swagger.io/swagger/media/assets/images/swagger_logo.svg\" align=\"right\" height=\"55\"\u003e](http://swagger.io/)\n\n[Swagger](https://swagger.io/) is an open-source software framework backed by a large ecosystem of tools that helps\ndevelopers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger\nUI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.\n\n[Swagger2Markup](https://github.com/Swagger2Markup/swagger2markup) converts a Swagger JSON or YAML file into one or more\nAsciiDoc or GitHub Flavored Markdown documents which can be combined with hand-written documentation. The Swagger source\nfile can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification.\nInternally it uses the official swagger-parser and my markup-document-builder.\n\nThis plugin processes the Swagger file to Pandoc markdown, and the converts the markdown to DITA using the\n[Pandoc DITA-OT Plugin](https://github.com/jason-fox/fox.jason.passthrough.pandoc)\n\n#### Sample Swagger Endpoint\n\n```json\n  \"paths\": {\n    \"/pet\": {\n      \"put\": {\n        \"tags\": [ \"pet\" ],\n        \"summary\": \"Update an existing pet\",\n        \"description\": \"\",\n        \"operationId\": \"updatePet\",\n        \"consumes\": [\"application/json\", \"application/xml\"],\n        \"produces\": [\"application/xml\", \"application/json\"],\n        \"parameters\": [\n          {\n            \"in\": \"body\", \"name\": \"body\",  \"required\": true,\n            \"description\": \"Pet object that needs to be added to the store\",\n            \"schema\": { \"$ref\": \"#/definitions/Pet\" }\n          }\n        ],\n        \"responses\": {\n          \"400\": {\"description\": \"Invalid ID supplied\"},\n          \"404\": {\"description\": \"Pet not found\"},\n          \"405\": {\"description\": \"Validation exception\"}\n        },\n        \"security\": [\n          {\n            \"petstore_auth\": [\"write:pets\",\"read:pets\"]\n          }\n        ]\n      }\n    },\n```\n\n#### Sample DITA Output\n\n\u003e ![](https://jason-fox.github.io/fox.jason.passthrough.swagger/request-formatted.png)\n\n## Install\n\nThe DITA-OT Swagger plug-in has been tested against [DITA-OT 3.x](http://www.dita-ot.org/download). It is recommended\nthat you upgrade to the latest version.\n\n### Installing DITA-OT\n\n\u003ca href=\"https://www.dita-ot.org\"\u003e\u003cimg src=\"https://www.dita-ot.org/images/dita-ot-logo.svg\" align=\"right\" height=\"55\"\u003e\u003c/a\u003e\n\nThe DITA-OT Swagger plug-in is a file reader for the DITA Open Toolkit.\n\n-   Full installation instructions for downloading DITA-OT can be found\n    [here](https://www.dita-ot.org/4.0/topics/installing-client.html).\n\n    1.  Download the `dita-ot-4.2.zip` package from the project website at\n        [dita-ot.org/download](https://www.dita-ot.org/download)\n    2.  Extract the contents of the package to the directory where you want to install DITA-OT.\n    3.  **Optional**: Add the absolute path for the `bin` directory to the _PATH_ system variable.\n\n    This defines the necessary environment variable to run the `dita` command from the command line.\n\n```console\ncurl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip\nunzip -q dita-ot-4.2.zip\nrm dita-ot-4.2.zip\n```\n\n### Installing the Plug-in\n\n-   Run the plug-in installation commands:\n\n```console\ndita install https://github.com/jason-fox/fox.jason.passthrough.pandoc/archive/master.zip\ndita install https://github.com/jason-fox/fox.jason.extend.css/archive/master.zip\ndita install https://github.com/jason-fox/fox.jason.passthrough.swagger/archive/master.zip\n```\n\nThe `dita` command line tool requires no additional configuration.\n\n---\n\n### Installing Pandoc\n\nTo download a copy follow the instructions on the [Install page](https://github.com/jgm/pandoc/blob/master/INSTALL.md)\n\n## Usage\n\nFor DITA processing, a swagger file can be defined in either `json` or `yaml` format.\nTo mark a file to be passed through for **Swagger** processing, label it with `format=\"swagger\"` within the `*.ditamap`\nas shown:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE bookmap PUBLIC \"-//OASIS//DTD DITA BookMap//EN\" \"bookmap.dtd\"\u003e\n\u003cbookmap\u003e\n    ...etc\n    \u003cappendices toc=\"yes\" print=\"yes\"\u003e\n      \u003ctopicmeta\u003e\n        \u003cnavtitle\u003eAppendices\u003c/navtitle\u003e\n      \u003c/topicmeta\u003e\n      \u003cappendix format=\"swagger\" href=\"Swagger_Definition.json\"/\u003e\n   \u003c/appendices\u003e\n\u003c/bookmap\u003e\n```\n\nThe additional file will be converted to a `*.dita` file and will be added to the build job without further processing.\nUnless overriden, the `navtitle` of the included topic will be the same as root name of the file. Any underscores in the\nfilename will be replaced by spaces in title.\n\n## License\n\n[Apache 2.0](LICENSE) © 2019 - 2024 Jason Fox\n\nThe Program includes the following additional software components which were obtained under license:\n\n-   swagger2markup-cli-2.0.0.jar - https://github.com/Swagger2Markup/swagger2markup - **Apache 2.0 license**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason-fox%2Ffox.jason.passthrough.swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjason-fox%2Ffox.jason.passthrough.swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason-fox%2Ffox.jason.passthrough.swagger/lists"}