Package: apispec-decorated-crawler
apispec-decorated-crawlerPlugin for apispec which helps reusing the documentation by using a decorated function stack.Extended ExampleWith this setup:fromapispecimportAPISpecfromflaskimportFlaskfrommarshmallowimportSchema,fieldsfrombrunoais.apispec.ext.decorated_crawlerimportdocd_wrapsapp=Flask(__name__)# Create an APISpecspec=APISpec(title='A safe Random swagger Petstore',version='1.0.0',plugins=['apispec.ext.flask','apispec.ext.marshmallow','brunoais.apispec.ext.decorated_crawler',],)defdecorates(func):@docd_wraps(func)defcalling(*args,**kwargs):"""---get:consumes:- application/xml+dec1security:- AlmostBasicAuth: []BasicAuth: []- ApiKeyAuth: []tags:- down1- up1responses:400:description: he may fail {f[x-400-suffix]}schema: PetSchema_:responses:400:description: Global failschema: PetSchema"""returnfunc(*args,**kwargs)returncallingdefdecorates2(func):@docd_wraps(func)defcalling(*args,**kwargs):"""---get:tags:- get2- up1security:- OAuth2: [scope1, scope2]responses:402:description: mefailschema: PetSchema"""returnfunc(*args,**kwargs)returncallingPassing a view function:@app.route('/random/<kind>')@decorates@decorates2defrandom_pet(kind):"""A cute furry animal endpoint.---post:description: POST a petget:description: Get a petsecurity:- ApiKeyAuth: []consumes:- application/json- application/xmlproduces:- application/json- application/xmlparameters:- in: pathname: kindrequired: truetype: stringdescription: Path Parameter description in Markdown.- in: queryname: offsettype: stringdescription: Query Parameter description in Markdown.responses:200:description: A pet to be returnedschema: PetSchema400:x-400-suffix: yeah yeah...."""pet={"category":[{"id":1,"name":"Named"}],"name":"woof"}returnjsonify(PetSchema().dump(pet).data)# Optional marshmallow supportclassCategorySchema(Schema):id=fields.Int()name=fields.Str(required=True)classPetSchema(Schema):category=fields.Nested(CategorySchema,many=True)name=fields.Str()spec.definition('Category',schema=CategorySchema)spec.definition('Pet',schema=PetSchema)withapp.test_request_context():spec.add_path(view=random_pet)The result becomesprint(spec.to_yaml())definitions:# ...info:{title:A safe Random swagger Petstore,version:1.0.0}paths:/random/{kind}:post:description:POST a petresponses:400:{description:Global fail,schema:PetSchema}get:consumes:[application/json,application/xml,application/xml+dec1]description:Get a petparameters:-{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 returnedschema:{$ref:'#/definitions/Pet'}400:{description:he may fail yeah yeah....,schema:PetSchema,x-400-suffix:yeahyeah....}402:{description:mefail,schema:PetSchema}security:-ApiKeyAuth:[]-AlmostBasicAuth:[]BasicAuth:[]-OAuth2:[scope1,scope2]tags:[down1,up1,get2]swagger:'2.0'tags:[]DetailsThis 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 toadd_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.Installationpip install apispec-decorated-crawlerLicenseThis is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.