基于 Swagger 描述语言为 REST API 生成 Markdown 文档

---
  swagger: "2.0"
  info: 
    version: "1.0.0"
    title: "Swagger Petstore"
    description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification"
    termsOfService: "http://swagger.io/terms/"
    contact: 
      name: "Swagger API Team"
    license: 
      name: "MIT"
  host: "petstore.swagger.io"
  basePath: "/api"
  schemes: 
    - "http"
  consumes: 
    - "application/json"
  produces: 
    - "application/json"
  paths: 
    /pets: 
      get: 
        description: "Returns all pets from the system that the user has access to"
        produces: 
          - "application/json"
        responses: 
          "200":
            description: "A list of pets."
            schema: 
              type: "array"
              items: 
                $ref: "#/definitions/Pet"
  definitions: 
    Pet: 
      type: "object"
      required: 
        - "id"
        - "name"
      properties: 
        id: 
          type: "integer"
          format: "int64"
        name: 
          type: "string"
        tag: 
          type: "string"

swagger2markup.markupLanguage=MARKDOWN

$ java -jar swagger2markup-cli-1.3.1.jar convert -i /path/to/petstore-minimal.yaml -f /tmp/petstore-minimal -c /path/to/config.properties

# Swagger Petstore


<a name="overview"></a>
## Overview
A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification


### Version information
*Version* : 1.0.0


### Contact information
*Contact* : Swagger API Team


### License information
*License* : MIT
*Terms of service* : http://swagger.io/terms/


### URI scheme
*Host* : petstore.swagger.io
*BasePath* : /api
*Schemes* : HTTP


### Consumes

* `application/json`


### Produces

* `application/json`




<a name="paths"></a>
## Paths

<a name="pets-get"></a>
### GET /pets

#### Description
Returns all pets from the system that the user has access to


#### Responses

|HTTP Code|Description|Schema|
|---|---|---|
|**200**|A list of pets.|< [Pet](#pet) > array|


#### Produces

* `application/json`




<a name="definitions"></a>
## Definitions

<a name="pet"></a>
### Pet

|Name|Schema|
|---|---|
|**id**  <br>*required*|integer (int64)|
|**name**  <br>*required*|string|
|**tag**  <br>*optional*|string|

# swagger2markdown.py

import os
import tempfile

from restart import status
from restart.api import RESTArt
from restart.parsers import Parser
from restart.renderers import Renderer
from restart.resource import Resource

api = RESTArt()


class SwaggerParser(Parser):

    content_type = 'text/plain'

    def parse(self, stream, content_type, content_length, context=None):
        return stream.read().decode('utf-8')


class MarkdownRenderer(Renderer):

    content_type = 'text/plain'
    format_suffix = 'md'

    def render(self, data, context=None):
        return data.encode('utf-8')


@api.register
class SwaggerMarkdownDocs(Resource):

    name = 'swagger_markdown_docs'

    parser_classes = (SwaggerParser,)
    renderer_classes = (MarkdownRenderer,)

    def create(self, request):
        with tempfile.NamedTemporaryFile(suffix='.yml', delete=False) as yml:
            yml_filename = yml.name
            yml.write(request.data.encode('utf-8'))

        with tempfile.NamedTemporaryFile(suffix='.md', delete=False) as md:
            md_filename = md.name

        jar = '/path/to/swagger2markup-cli-1.3.1.jar'
        conf = '/path/to/config.properties'
        os.system('java -jar {jar} convert -i {yml} -f {md} -c {conf}'.format(
            jar=jar, yml=yml_filename, md=md_filename[:-len('.md')], conf=conf,
        ))

        with open(md_filename) as md:
            content = md.read().decode('utf-8')

        os.unlink(yml_filename)
        os.unlink(md_filename)

        return content, status.HTTP_201_CREATED

$ restart swagger2markdown:api
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

$ curl -H 'Content-Type: text/plain' -XPOST http://localhost:5000/swagger_markdown_docs --data-binary @/path/to/petstore-minimal.yaml > /tmp/petstore-minimal.md