Git Product home page Git Product logo

apispec-decorated-crawler's Introduction

apispec-decorated-crawler

Plugin for apispec which helps reusing the documentation by using a decorated function stack.

Extended Example

With this setup:

from apispec import APISpec
from flask import Flask
from marshmallow import Schema, fields

from brunoais.apispec.ext.decorated_crawler import docd_wraps

app = Flask(__name__)

# Create an APISpec
spec = APISpec(
    title='A safe Random swagger Petstore',
    version='1.0.0',
    plugins=[
        'apispec.ext.flask',
        'apispec.ext.marshmallow',
        'brunoais.apispec.ext.decorated_crawler',
    ],
)


def decorates(func):
    @docd_wraps(func)
    def calling(*args, **kwargs):
        """
            ---
            get:
                consumes:
                  - application/xml+dec1
                security:
                    - AlmostBasicAuth: []
                      BasicAuth: []
                    - ApiKeyAuth: []
                tags:
                    - down1
                    - up1
                responses:
                    400:
                        description: he may fail {f[x-400-suffix]}
                        schema: PetSchema
            _:
                responses:
                    400:
                        description: Global fail
                        schema: PetSchema
        """
        return func(*args, **kwargs)

    return calling


def decorates2(func):
    @docd_wraps(func)
    def calling(*args, **kwargs):
        """
        ---
        get:
            tags:
                - get2
                - up1
            security:
                - OAuth2: [scope1, scope2]
            responses:
                402:
                    description: mefail
                    schema: PetSchema
        """

        return func(*args, **kwargs)

    return calling

Passing a view function:

@app.route('/random/<kind>')
@decorates
@decorates2
def random_pet(kind):
    """

    A cute furry animal endpoint.
    ---

    post:
        description: POST a pet
    get:
        description: Get a pet
        security:
            - ApiKeyAuth: []
        consumes:
          - application/json
          - application/xml
        produces:
          - application/json
          - application/xml
        parameters:
            - in: path
              name: kind
              required: true
              type: string
              description: Path Parameter description in Markdown.
            - in: query
              name: offset
              type: string
              description: Query Parameter description in Markdown.
        responses:
            200:
                description: A pet to be returned
                schema: PetSchema
            400:
                x-400-suffix: yeah yeah....
    """
    pet = {
        "category": [{
            "id": 1,
            "name": "Named"
        }],
        "name": "woof"
    }
    return jsonify(PetSchema().dump(pet).data)

# Optional marshmallow support
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

class PetSchema(Schema):
    category = fields.Nested(CategorySchema, many=True)
    name = fields.Str()

spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema)

with app.test_request_context():
    spec.add_path(view=random_pet)

The result becomes

print(spec.to_yaml())
definitions:
# ...
info: {title: A safe Random swagger Petstore, version: 1.0.0}
paths:
  /random/{kind}:
    post:
      description: POST a pet
      responses:
        400: {description: Global fail, schema: PetSchema}
    get:
      consumes: [application/json, application/xml, application/xml+dec1]
      description: Get a pet
      parameters:
      - {description: Path Parameter description in Markdown., in: path, name: kind,
        required: true, type: string}
      - {description: Query Parameter description in Markdown., in: query, name: offset,
        type: string}
      produces: [application/json, application/xml]
      responses:
        200:
          description: A pet to be returned
          schema: {$ref: '#/definitions/Pet'}
        400: {description: he may fail yeah yeah...., schema: PetSchema, x-400-suffix: yeah
            yeah....}
        402: {description: mefail, schema: PetSchema}
      security:
      - ApiKeyAuth: []
      - AlmostBasicAuth: []
        BasicAuth: []
      - OAuth2: [scope1, scope2]
      tags: [down1, up1, get2]
swagger: '2.0'
tags: []

Details

This is an operations helper that allows you to pass a decorated view and get the combined documentation of all decorator functions. It required the view passed to add_path. Inspects view docstrings and its docd_wraps decorator functions and merges all the documentation into a single document. Useful if you use decorators to manage authentication or even if you have shared error pages and you do not want to document common error states (status 400, status 500, etc...) individually on all views.

All documentation is merged from bottom-up, starting on the view function and ending on the topmost decorator. Decorators can declare a "special" HTTP method called _ (underscore). That one is applied last for all methods, also from bottom up, in a subsequent pass.

Installation

pip install apispec-decorated-crawler

License

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

apispec-decorated-crawler's People

Contributors

brunoais avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.