{"id":20279735,"url":"https://github.com/genieframework/swaggermarkdown.jl","last_synced_at":"2025-03-04T02:41:13.149Z","repository":{"id":40990300,"uuid":"366531290","full_name":"GenieFramework/SwaggerMarkdown.jl","owner":"GenieFramework","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-18T18:38:29.000Z","size":53,"stargazers_count":11,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-21T15:04:09.153Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GenieFramework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2021-05-11T22:48:52.000Z","updated_at":"2025-01-22T08:02:03.000Z","dependencies_parsed_at":"2023-11-10T11:26:45.586Z","dependency_job_id":"61ee7c04-15c9-4eb6-a4d2-73f0bb9cc9cc","html_url":"https://github.com/GenieFramework/SwaggerMarkdown.jl","commit_stats":{"total_commits":19,"total_committers":3,"mean_commits":6.333333333333333,"dds":0.5263157894736843,"last_synced_commit":"b40dd5561a14d4b9f5b115bd2956c71a4eac937b"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenieFramework%2FSwaggerMarkdown.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenieFramework%2FSwaggerMarkdown.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenieFramework%2FSwaggerMarkdown.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenieFramework%2FSwaggerMarkdown.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GenieFramework","download_url":"https://codeload.github.com/GenieFramework/SwaggerMarkdown.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241773256,"owners_count":20018064,"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":[],"created_at":"2024-11-14T13:32:47.526Z","updated_at":"2025-03-04T02:41:13.128Z","avatar_url":"https://github.com/GenieFramework.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Julia Swagger Markdown\n[![codecov](https://codecov.io/gh/jiachengzhang1/SwaggerMarkdown/branch/master/graph/badge.svg?token=GF65PUANJ2)](https://codecov.io/gh/jiachengzhang1/SwaggerMarkdown)\n\nSwagger Markdown allows you to generate `swagger.json` for API documentation from the julia source code. The package uses marco to process the markdown that contains an API endpoint's documentation. The markdowon needs to follow the `paths` described by the OpenAPI Specification ([v3](https://swagger.io/specification/#paths-object), [v2](https://swagger.io/docs/specification/2-0/paths-and-operations/)), and in YAML format.\n\nFor more information about OpenAPI Specification, [version 3](https://swagger.io/docs/specification/basic-structure/), [version 2](https://swagger.io/docs/specification/2-0/basic-structure/).\n\nThe package is inspired by, and it uses the similar style as [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc).\n\n## Installation\n\n```julia\njulia\u003e ]\npkg\u003e add SwaggerMarkdown\n```\n\n## Usage\n\nWrite markdown for the documentation of the API endpoints. The markdowon needs to follow the `paths` described by the OpenAPI Specification ([version 3](https://swagger.io/specification/#paths-object), [version 2](https://swagger.io/docs/specification/2-0/paths-and-operations/)), and in YAML format.\n\n\n```julia\nusing JSON\nusing SwaggerMarkdown\n\n@swagger \"\"\"\n/doge:\n  get:\n    description: doge\n    responses:\n      '200':\n        description: Returns a doge.\n\"\"\"\n\n# the version of the OpenAPI used is required\nopenApi_version = \"2.0\"\n\n# the info of the API, title and version of the info are required\ninfo = Dict{String, Any}()\ninfo[\"title\"] = \"Doge to the moon\"\ninfo[\"version\"] = \"1.0.5\"\n\nopenApi = OpenAPI(openApi_version, info)\n\nswagger_document = build(openApi)\nswagger_json = JSON.json(swagger_document)\n```\n\n**Note: make sure the the version in the `SwaggerMarkdown.OpenAPI` matches the version used in markdown.**\n\nThe json generated by `JSON.json(swagger_document)`:\n\n```json\n{\n    \"swagger\": \"2.0\",\n    \"paths\": {\n        \"/doge\": {\n            \"get\": {\n                \"responses\": {\n                    \"200\": {\n                        \"description\": \"Returns a doge.\"\n                    }\n                },\n                \"description\": \"doge\"\n            }\n        }\n    },\n    \"info\": {\n        \"title\": \"Doge to the moon\",\n        \"version\": \"1.0.5\"\n    }\n}\n```\n### Base path\n\nIf your API sits behind a reverse proxy with a base path, you'll need to set the `servers` optional field as\n\n```julia\noptional_fields[\"servers\"] = [Dict(\"url\" =\u003e ENV[\"BASEPATH\"])]\nopenApi = OpenAPI(\"3.0\", info, optional_fields=optional_fields)\n```\n\nFor OpenAPI 2.0, use the `basePath`optional field as\n\n```julia\noptional_fields[\"basePath\"] = ENV[\"BASEPATH\"]\nopenApi = OpenAPI(\"3.0\", info, optional_fields=optional_fields)\n```\n\n### Components\n\n[Components](https://swagger.io/docs/specification/v3_0/components/) are supported by additional macros.\n\n- `@swagger_schemas`\n- `@swagger_parameters`\n- `@swagger_requestBodies`\n- `@swagger_responses`\n- `@swagger_headers`\n- `@swagger_examples`\n- `@swagger_links`\n- `@swagger_callbacks`\n\nThese can be used anywhere in the code. The following example declares a `User` schema which can be [referenced](https://swagger.io/docs/specification/v3_0/using-ref/).\n\n```julia\nusing JSON\nusing SwaggerMarkdown\n\n@swagger_schemas \"\"\"\nUser:\n  properties:\n    id:\n      type: integer\n    name:\n      type: string\n\"\"\"\n```\n\nThe schema can then be used to describe e.g. the response of an endpoint.\n\n```julia\n@swagger \"\"\"\n/user:\n  get:\n    description: Get a user\n    responses:\n      '200':\n        description: Successful retrieval of a user\n        schema:\n          \\$ref: \"#/components/schemas/User\"\n\"\"\"\n```\n\nPlease note the `\\` in front of `$ref` for escaping the `$` which is normally used for string interpolation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenieframework%2Fswaggermarkdown.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenieframework%2Fswaggermarkdown.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenieframework%2Fswaggermarkdown.jl/lists"}