Skip to main content

A Python Markdown extension to include Swagger informations in your documentation

Project description

swagger-markdown

A Python Markdown extension to include Swagger Definitions and Paths in your markdown documentation. This extension works with Swagger 2.0 JSON files.

For now this extension supports only Definitions and Paths and can do those things:

  • For Definitions it can create description tables.
  • For Paths it can create request parameters table, request examples, response tables, and responses examples.

To install:

pip install swagger-markdown

How to use with python-markdown

import markdown
from swaggermarkdown import SwaggerExtension

md = markdown.Markdown(extensions=[SwaggerExtension()])
text = ':swg-def: FirstDefinition'
converted = md.convert(text)

Or more simply

import markdown

markdown.markdown('some markdown', extensions=['swaggermarkdown']))

Configuration

SwaggerExtension(
  definitionsUrlRoot='/types',    # add an url in front of definition links (only if not present in current page)
  file='tests/test_swagger.json'  # redefine the default file (default: swagger.json)
)

How to use with MkDocs

markdown_extensions:
  - swaggermarkdown

You have the option to define some configuration for the extension as well here:

markdown_extensions:
  - swaggermarkdown:
      file: swagger.json
      definitionsUrlRoot: '/types'

How to use in your markdown files

## My Pet Api

### Endpoint /pet/findByTags

:swg-path: /pet/findByTags

### Pet definition

:swg-def: Pet

You should get a table similar to this

Individual configuration for Paths and Definition

You can decide with more precision what you want to show by defining a YAML configuration for each Path and Definition. The YAML definition must be indented with 4 spaces:

:swg-path: /pet/{petId}/uploadImage
    verbs:
      - post
      - get
    sections:
      parametersTable: true
      requestExamples: true
      requestCodeExamples: true
      responseTable: true
      responseExamples: true


:swg-def: Pet
    properties:
      photoUrls:
        hide: true
      id:
        description: "New description"

For now only the options presented above are supported

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swagger-markdown-0.9.16.tar.gz (8.2 kB view details)

Uploaded Source

File details

Details for the file swagger-markdown-0.9.16.tar.gz.

File metadata

  • Download URL: swagger-markdown-0.9.16.tar.gz
  • Upload date:
  • Size: 8.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.1 setuptools/51.0.0 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.9.1

File hashes

Hashes for swagger-markdown-0.9.16.tar.gz
Algorithm Hash digest
SHA256 0413837a763a3aefe531688160fc4795788f479e4fec4b9c54f1ab428b5e7a04
MD5 6a4ee495cb0d191068b2f655205186da
BLAKE2b-256 a1994636f8e7d20afe176c989ea92227cc90ad0cad880b0d99a313d9e4230b5d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page