一个可插拔的API规范生成器。目前支持OpenAPI规范(以前称为Swagger规范)。
项目描述
一个可插拔的API规范生成器。目前支持OpenAPI规范(以前称为Swagger规范)。
特性
支持OpenAPI规范(版本2和3)
框架无关
内置对marshmallow的支持
解析文档字符串的实用工具
安装
$ pip install -U apispec
在使用棉花糖插件时,请确保使用兼容的棉花糖版本。
$ pip install -U apispec[marshmallow]
示例应用
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin
from flask import Flask
from marshmallow import Schema, fields
# Create an APISpec
spec = APISpec(
title="Swagger Petstore",
version="1.0.0",
openapi_version="3.0.2",
plugins=[FlaskPlugin(), MarshmallowPlugin()],
)
# Optional marshmallow support
class CategorySchema(Schema):
id = fields.Int()
name = fields.Str(required=True)
class PetSchema(Schema):
category = fields.List(fields.Nested(CategorySchema))
name = fields.Str()
# Optional security scheme support
api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
# Optional Flask support
app = Flask(__name__)
@app.route("/random")
def random_pet():
"""A cute furry animal endpoint.
---
get:
description: Get a random pet
security:
- ApiKeyAuth: []
responses:
200:
content:
application/json:
schema: PetSchema
"""
pet = get_random_pet()
return PetSchema().dump(pet)
# Register the path and the entities within it
with app.test_request_context():
spec.path(view=random_pet)
生成的OpenAPI规范
import json
print(json.dumps(spec.to_dict(), indent=2))
# {
# "paths": {
# "/random": {
# "get": {
# "description": "Get a random pet",
# "security": [
# {
# "ApiKeyAuth": []
# }
# ],
# "responses": {
# "200": {
# "content": {
# "application/json": {
# "schema": {
# "$ref": "#/components/schemas/Pet"
# }
# }
# }
# }
# }
# }
# }
# },
# "tags": [],
# "info": {
# "title": "Swagger Petstore",
# "version": "1.0.0"
# },
# "openapi": "3.0.2",
# "components": {
# "parameters": {},
# "responses": {},
# "schemas": {
# "Category": {
# "type": "object",
# "properties": {
# "name": {
# "type": "string"
# },
# "id": {
# "type": "integer",
# "format": "int32"
# }
# },
# "required": [
# "name"
# ]
# },
# "Pet": {
# "type": "object",
# "properties": {
# "name": {
# "type": "string"
# },
# "category": {
# "type": "array",
# "items": {
# "$ref": "#/components/schemas/Category"
# }
# }
# }
# }
# "securitySchemes": {
# "ApiKeyAuth": {
# "type": "apiKey",
# "in": "header",
# "name": "X-API-Key"
# }
# }
# }
# }
# }
print(spec.to_yaml())
# components:
# parameters: {}
# responses: {}
# schemas:
# Category:
# properties:
# id: {format: int32, type: integer}
# name: {type: string}
# required: [name]
# type: object
# Pet:
# properties:
# category:
# items: {$ref: '#/components/schemas/Category'}
# type: array
# name: {type: string}
# type: object
# securitySchemes:
# ApiKeyAuth:
# in: header
# name: X-API-KEY
# type: apiKey
# info: {title: Swagger Petstore, version: 1.0.0}
# openapi: 3.0.2
# paths:
# /random:
# get:
# description: Get a random pet
# responses:
# 200:
# content:
# application/json:
# schema: {$ref: '#/components/schemas/Pet'}
# security:
# - ApiKeyAuth: []
# tags: []
文档
文档可在https://apispec.readthedocs.io/ 查找。
生态系统
有关apispec相关库的列表可在GitHub wiki中找到
支持apispec
apispec由一群志愿者维护。如果您想支持项目的未来,请考虑向我们的Open Collective捐赠。
专业支持
通过Tidelift订阅可以获得专业支持。
Tidelift为软件开发团队提供了一个购买和维护其软件的单一来源,同时与现有工具无缝集成,并从最了解其专家那里获得专业级保障。[获取专业支持]
安全联系方式
如需报告安全漏洞,请使用Tidelift安全联系方式。Tidelift将协调修复和披露。
项目链接
许可证
MIT授权。有关更多详细信息,请参阅捆绑的LICENSE文件。
项目详情
下载文件
下载您平台对应的文件。如果您不确定选择哪个,请了解更多关于安装包的信息。
源分发
apispec-6.6.1.tar.gz (76.5 kB 查看散列值)
构建分发
apispec-6.6.1-py3-none-any.whl (30.4 kB 查看散列值)
关闭
apispec-6.6.1.tar.gz的散列值
算法 | 散列摘要 | |
---|---|---|
SHA256 | f5caa47cee75fe03b9c50b5594048b4c052eeca2c212e0dac12dbb6175d9a659 |
|
MD5 | 6d4983057ff8ddb5d9ab328fec6abea0 |
|
BLAKE2b-256 | ab5b5d94e1ec6a8e487c026b2a7518dfb7ea90c4c82db48de33c227b7c9141fb |
关闭
apispec-6.6.1-py3-none-any.whl的散列值
算法 | 散列摘要 | |
---|---|---|
SHA256 | 6460315cb38ac6a2ff42d9e2b8dc0435c37d4428d3abeda96ff97b5dc8eb6b94 |
|
MD5 | 3beedae40cbaa9502230a74953bfedd4 |
|
BLAKE2b-256 | ec0f1d0aabf69a9a1bdf8ed1461a2ec7b4036ff4da501f6db2e37634b01860e3 |