Package: python-openapi
Generate an OpenAPI specification from a Python classPyOpenAPIproduces an OpenAPI specification in JSON, YAML or HTML format with endpoint definitions extracted from member functions of a strongly-typed Python class.Featuressupports standard and asynchronous functions (async def)maps function name prefixes such asget_orcreate_to HTTP GET, POST, PUT, DELETE, PATCHhandles both simple and composite types (int,str,Enum,@dataclass)handles generic types (List[T],Dict[K, V],Optional[T],Union[T1, T2, T3])maps Python positional-only and keyword-only arguments (of simple types) to path and query parameters, respectivelymaps composite types to HTTP request bodysupports user-defined routes, request and response samples with decorator@webmethodextracts description text from class and function doc-strings (__doc__)recognizes parameter description text given in reStructuredText doc-string format (:param name: ...)converts exceptions declared in doc-strings into HTTP 4xx and 5xx responses (e.g.:raises TypeError:)recursively converts composite types into JSON schemasgroups frequently used composite types into a separate section and re-uses them with$refdisplays generated OpenAPI specification in HTML withReDocLive examplesEndpoint definition in PythonGenerated OpenAPI specification in JSONGenerated OpenAPI specification in YAMLGenerated OpenAPI specification in HTML with ReDocUser guideThe specification objectIn order to generate anOpenAPI specification document, you should first construct aSpecificationobject, which encapsulates the formal definition:specification=Specification(MyEndpoint,Options(server=Server(url="http://example.com/api"),info=Info(title="Example specification",version="1.0",description=description,),default_security_scheme=SecuritySchemeHTTP("Authenticates a request by verifying a JWT (JSON Web Token) passed in the `Authorization` HTTP header.","bearer","JWT",),extra_types=[ExampleType,UnreferencedType],error_wrapper=True,),)The first argument toSpecificationis a Python class (type) whose methods will be inspected and converted into OpenAPI endpoint operations. The second argument is additional options that fine-tune how the specification is generated.Defining endpoint operationsLet's take a look at the definition of a simple endpoint calledJobManagement:classJobManagement:defcreate_job(self,items:List[URL])->uuid.UUID:...defget_job(self,job_id:uuid.UUID,/,format:Format)->Job:...defremove_job(self,job_id:uuid.UUID,/)->None:...defupdate_job(self,job_id:uuid.UUID,/,job:Job)->None:...The name of each method begins with a prefix such ascreate,get,removeorupdate, each of which maps to an HTTP verb, e.g.POST,GET,DELETEorPATCH. The rest of the function name serves as an identifier, e.g.job. Theselfargument to the function is ignored. Other arguments indicate what path and queryparameter objects, and whatHTTP request bodythe operation accepts.Function signatures for operationsFunction signatures for operations must have full type annotation, including parameter types and return type.Pythonpositional-only argumentsmap to path parameters. Python positional-or-keyword arguments map to query parameters if they are of a simple type (e.g.intorstr). If a composite type (e.g. a class, a list or a union) occurs in the Python parameter list, it is treated as the definition of the HTTP request body. Only one composite type may appear in the parameter list. The return type of the function is treated as the HTTP response body. If the function returnsNone, it corresponds to an HTTP response with no payload (i.e. aContent-Lengthof 0).The JSON schema for the HTTP request and response body is generated with the libraryjson_strong_typing, and is automatically embedded in the OpenAPI specification document.User-defined operation pathBy default, the library constructs the operation path from the Python function name and positional-only parameters. However, it is possible to supply a custom path (route) using the@webmethoddecorator:@webmethod(route="/person/name/{family}/{given}",)defget_person_by_name(self,family:str,given:str,/)->Person:...The custom path must have placeholders for all positional-only parameters in the function signature, and vice versa.Documenting operationsUse Python ReST (ReStructured Text) doc-strings to attach documentation to operations:defget_job(self,job_id:uuid.UUID,/,format:Format)->Job:"""Query status information about a job.:param job_id: Unique identifier for the job to query.:returns: Status information about the job.:raises NotFoundError: The job does not exist.:raises ValidationError: The input is malformed."""...Fields such asparamandreturnshelp document path and query parameters, HTTP request and response body. The fieldraiseshelps document error responses by identifying the exact return type when an error occurs. The Python type forreturnsandraisesis translated to a JSON schema and embedded in the OpenAPI specification document.Request and response examplesOpenAPI supports specifyingexamplesfor the HTTP request and response body of endpoint operations. This is supported via the@webmethoddecorator:@webmethod(route="/member/name/{family}/{given}",response_examples=[Student("Szörnyeteg","Lajos"),Student("Ló","Szerafin"),Student("Bruckner","Szigfrid"),Student("Nagy","Zoárd"),Teacher("Mikka","Makka","Négyszögletű Kerek Erdő"),Teacher("Vacska","Mati","Négyszögletű Kerek Erdő"),],)defget_member_by_name(self,family:str,given:str,/)->Union[Student,Teacher]:...A response example may be an exception or error class (a type that derives fromException). These are usually shown under an HTTP status code of 4xx or 5xx.The Python objects inrequest_examplesandresponse_examplesare translated to JSON with the libraryjson_strong_typing.Mapping function name prefixes to HTTP verbsThe following table identifies which function name prefixes map to which HTTP verbs:PrefixHTTP verbcreatePOSTdeleteREMOVEdoGET or POSTgetGETpostPOSTputPOSTremoveREMOVEsetPUTupdatePATCHIf the function signature conflicts with the HTTP verb (e.g. a function name starts withgetbut has a composite type in the parameter list, which maps to a non-empty HTTP request body), the HTTP verb is automatically adjusted.Associating HTTP status codes with response typesBy default, the library associates success responses with HTTP status code 200, and error responses with HTTP status code 500. However, it is possible to associate any Python type with any HTTP status code:specification=Specification(MyEndpoint,Options(server=Server(url="http://example.com/api"),info=Info(title="Example specification",version="1.0",description=description,),success_responses={Student:HTTPStatus.CREATED,Teacher:HTTPStatus.ACCEPTED,},error_responses={AuthenticationError:HTTPStatus.UNAUTHORIZED,BadRequestError:400,InternalServerError:500,NotFoundError:HTTPStatus.NOT_FOUND,ValidationError:"400",},error_wrapper=True,),)The argumentssuccess_responsesanderror_responsestake a dictionary that maps types to status codes. Status codes may be integers (e.g.400), strings (e.g."400"or"4xx") orHTTPStatusenumeration values. The string representation of the status code must be valid as per the OpenAPI specification.