Falcon plugin for APICEPEC documentation generation.
falcon-apispec的Python项目详细描述
猎鹰APISpec
apispec为Falconweb应用程序生成openapi规范(又名swagger)的插件。
安装
pip install falcon-apispec
使用apispec v1.0+
。
示例应用程序
fromapispecimportAPISpecfromapispec.ext.marshmallowimportMarshmallowPluginimportfalconfromfalcon_apispecimportFalconPluginfrommarshmallowimportSchema,fields# Optional marshmallow supportclassCategorySchema(Schema):id=fields.Int()name=fields.Str(required=True)classPetSchema(Schema):category=fields.Nested(CategorySchema,many=True)name=fields.Str()# Create Falcon web appapp=falcon.API()classRandomPetResource:defon_get(self,req,resp):"""A cute furry animal endpoint. --- get: description: Get a random pet responses: 200: description: A pet to be returned schema: PetSchema """pet=get_random_pet()# returns JSONresp.media=pet# create instance of resourcerandom_pet_resource=RandomPetResource()# pass into `add_route` for Falconapp.add_route("/random",random_pet_resource)# Create an APISpecspec=APISpec(title='Swagger Petstore',version='1.0.0',openapi_version='2.0',plugins=[FalconPlugin(app),MarshmallowPlugin(),],)# Register entities and pathsspec.components.schema('Category',schema=CategorySchema)spec.components.schema('Pet',schema=PetSchema)# pass created resource into `path` for APISpecspec.path(resource=random_pet_resource)
生成的openapi规范
spec.to_dict()# {# "info": {# "title": "Swagger Petstore",# "version": "1.0.0"# },# "swagger": "2.0",# "paths": {# "/random": {# "get": {# "description": "A cute furry animal endpoint.",# "responses": {# "200": {# "schema": {# "$ref": "#/definitions/Pet"# },# "description": "A pet to be returned"# }# },# }# }# },# "definitions": {# "Pet": {# "properties": {# "category": {# "type": "array",# "items": {# "$ref": "#/definitions/Category"# }# },# "name": {# "type": "string"# }# }# },# "Category": {# "required": [# "name"# ],# "properties": {# "name": {# "type": "string"# },# "id": {# "type": "integer",# "format": "int32"# }# }# }# },# }spec.to_yaml()# definitions:# Pet:# enum: [name, photoUrls]# properties:# id: {format: int64, type: integer}# name: {example: doggie, type: string}# info: {description: 'This is a sample Petstore server. You can find out more ', title: Swagger Petstore, version: 1.0.0}# parameters: {}# paths: {}# security:# - apiKey: []# swagger: '2.0'# tags: []
贡献
为地方发展而设立
- Github上的Fork Falcon APISpec
- 安装开发需求。强烈建议使用虚拟环境
pip install -r requirements.txt
运行测试
pytest