From ba94374c87f4e7942088be41d175bd51ab4bee8d Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Mon, 22 Jul 2024 09:03:04 +0000 Subject: [PATCH] build based on 4c7260c --- dev/index.html | 2 +- dev/reference/index.html | 14 +++++++------- dev/search/index.html | 2 +- dev/todo/index.html | 2 +- dev/tools/index.html | 2 +- dev/userguide/index.html | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/dev/index.html b/dev/index.html index 9d850ba..482d922 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · OpenAPI.jl
Edit on GitHub

OpenAPI.jl

This is the Julia library needed along with code generated by the OpenAPI generator to help define, produce and consume OpenAPI interfaces.

The goal of OpenAPI is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.

Check out OpenAPI-Spec for additional information about the OpenAPI project, including additional libraries with support for other languages and more.

Migrating from Swagger.jl

This package supersedes the Swagger.jl package. OpenAPI.jl and the associated generator can address both OpenAPI 2.x (Swagger) and OpenAPI 3.x specifications. Code dependent on Swagger.jl would not directly work with OpenAPI.jl, but migration should not be too difficult.

+Home · OpenAPI.jl
Edit on GitHub

OpenAPI.jl

This is the Julia library needed along with code generated by the OpenAPI generator to help define, produce and consume OpenAPI interfaces.

The goal of OpenAPI is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.

Check out OpenAPI-Spec for additional information about the OpenAPI project, including additional libraries with support for other languages and more.

Migrating from Swagger.jl

This package supersedes the Swagger.jl package. OpenAPI.jl and the associated generator can address both OpenAPI 2.x (Swagger) and OpenAPI 3.x specifications. Code dependent on Swagger.jl would not directly work with OpenAPI.jl, but migration should not be too difficult.

diff --git a/dev/reference/index.html b/dev/reference/index.html index 8df5ac0..469a0ab 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -8,7 +8,7 @@ escape_path_params::Union{Nothing,Bool}=nothing, chunk_reader_type::Union{Nothing,Type{<:AbstractChunkReader}}=nothing, verbose::Union{Bool,Function}=false, -)

Create a new OpenAPI client context.

A client context holds common information to be used across APIs. It also holds a connection to the server and uses that across API calls. The client context needs to be passed as the first parameter of all API calls.

Parameters:

Keyword parameters:

source
OpenAPI.Clients.set_user_agent — Function
set_user_agent(client::Client, ua::String)

Set the User-Agent header to be sent with all API calls.

source
OpenAPI.Clients.set_cookie — Function
set_cookie(client::Client, ck::String)

Set the Cookie header to be sent with all API calls.

source
OpenAPI.Clients.set_header — Function
set_header(client::Client, name::String, value::String)

Set the specified header to be sent with all API calls.

source
OpenAPI.Clients.set_timeout — Function
set_timeout(client::Client, timeout::Int)

Set the timeout in seconds for all API calls.

source

Examining Models

Base.hasproperty — Function
hasproperty(x, s::Symbol)

Return a boolean indicating whether the object x has s as one of its own properties.

Julia 1.2

This function requires at least Julia 1.2.

See also: propertynames, hasfield.

source
Base.getproperty — Function
getproperty(value, name::Symbol)
+)

Create a new OpenAPI client context.

A client context holds common information to be used across APIs. It also holds a connection to the server and uses that across API calls. The client context needs to be passed as the first parameter of all API calls.

Parameters:

  • root: The root URL of the server. This is the base URL that will be used for all API calls.

Keyword parameters:

  • headers: A dictionary of HTTP headers to be sent with all API calls.
  • get_return_type: A function that is called to determine the return type of an API call. This function is called with the following parameters:
    • return_types: A dictionary of regular expressions and their corresponding return types. The regular expressions are matched against the HTTP status code of the response.
    • response_code: The HTTP status code of the response.
    • response_data: The response data as a string.
    The function should return the return type to be used for the API call.
  • long_polling_timeout: The timeout in seconds for long polling requests. This is the time after which the request will be aborted if no data is received from the server.
  • timeout: The timeout in seconds for all other requests. This is the time after which the request will be aborted if no data is received from the server.
  • pre_request_hook: A function that is called before every API call. This function must provide two methods:
    • pre_request_hook(ctx::Ctx): This method is called before every API call. It is passed the context object that will be used for the API call. The function should return the context object to be used for the API call.
    • pre_request_hook(resource_path::AbstractString, body::Any, headers::Dict{String,String}): This method is called before every API call. It is passed the resource path, request body and request headers that will be used for the API call. The function should return those after making any modifications to them.
  • escape_path_params: Whether the path parameters should be escaped before being used in the URL. This is useful if the path parameters contain characters that are not allowed in URLs or contain path separators themselves.
  • chunk_reader_type: The type of chunk reader to be used for streaming responses. This can be one of LineChunkReader, JSONChunkReader or RFC7464ChunkReader. If not specified, then the type is automatically determined based on the return type of the API call.
  • verbose: Can be set either to a boolean or a function.
    • If set to true, then the client will log all HTTP requests and responses.
    • If set to a function, then that function will be called with the following parameters:
      • type: The type of message.
      • message: The message to be logged.
source
OpenAPI.Clients.set_user_agent — Function
set_user_agent(client::Client, ua::String)

Set the User-Agent header to be sent with all API calls.

source
OpenAPI.Clients.set_cookie — Function
set_cookie(client::Client, ck::String)

Set the Cookie header to be sent with all API calls.

source
OpenAPI.Clients.set_header — Function
set_header(client::Client, name::String, value::String)

Set the specified header to be sent with all API calls.

source
OpenAPI.Clients.set_timeout — Function
set_timeout(client::Client, timeout::Int)

Set the timeout in seconds for all API calls.

source

Examining Models

Base.hasproperty — Function
hasproperty(x, s::Symbol)

Return a boolean indicating whether the object x has s as one of its own properties.

Julia 1.2

This function requires at least Julia 1.2.

See also: propertynames, hasfield.

source
Base.getproperty — Function
getproperty(value, name::Symbol)
 getproperty(value, name::Symbol, order::Symbol)

The syntax a.b calls getproperty(a, :b). The syntax @atomic order a.b calls getproperty(a, :b, :order) and the syntax @atomic a.b calls getproperty(a, :b, :sequentially_consistent).

Examples

julia> struct MyType{T <: Number}
            x::T
        end
@@ -28,7 +28,7 @@
 
 julia> obj.x
 1

One should overload getproperty only when necessary, as it can be confusing if the behavior of the syntax obj.f is unusual. Also note that using methods is often preferable. See also this style guide documentation for more information: Prefer exported methods over direct field access.

See also getfield, propertynames and setproperty!.

source
Base.setproperty! — Function
setproperty!(value, name::Symbol, x)
-setproperty!(value, name::Symbol, x, order::Symbol)

The syntax a.b = c calls setproperty!(a, :b, c). The syntax @atomic order a.b = c calls setproperty!(a, :b, c, :order) and the syntax @atomic a.b = c calls setproperty!(a, :b, c, :sequentially_consistent).

Julia 1.8

setproperty! on modules requires at least Julia 1.8.

See also setfield!, propertynames and getproperty.

source
OpenAPI.Clients.getpropertyat — Function
getpropertyat(o::T, path...) where {T<:APIModel}

Returns the property at the specified path. The path can be a single property name or a chain of property names separated by dots, representing a nested property.

source
OpenAPI.Clients.haspropertyat — Function
haspropertyat(o::T, path...) where {T<:APIModel}

Returns true if the supplied object has the property at the specified path.

source

Examining Client API Response

OpenAPI.Clients.ApiResponse — Type
ApiResponse

Represents the HTTP API response from the server. This is returned as the second return value from all API calls.

Properties available:

  • status: the HTTP status code
  • message: the HTTP status message
  • headers: the HTTP headers
  • raw: the raw response ( as a Downloads.Response object)
source
OpenAPI.Clients.is_longpoll_timeout — Function
is_longpoll_timeout(ex::Exception)

Examine the supplied exception and return true if the reason is timeout of a long polling request. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

source
OpenAPI.Clients.is_request_interrupted — Function
is_request_interrupted(ex::Exception)

Examine the supplied exception and return true if the reason is that the request was interrupted. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

source
OpenAPI.Clients.storefile — Function
storefile(api_call::Function;
+setproperty!(value, name::Symbol, x, order::Symbol)

The syntax a.b = c calls setproperty!(a, :b, c). The syntax @atomic order a.b = c calls setproperty!(a, :b, c, :order) and the syntax @atomic a.b = c calls setproperty!(a, :b, c, :sequentially_consistent).

Julia 1.8

setproperty! on modules requires at least Julia 1.8.

See also setfield!, propertynames and getproperty.

source
OpenAPI.Clients.getpropertyat — Function
getpropertyat(o::T, path...) where {T<:APIModel}

Returns the property at the specified path. The path can be a single property name or a chain of property names separated by dots, representing a nested property.

source
OpenAPI.Clients.haspropertyat — Function
haspropertyat(o::T, path...) where {T<:APIModel}

Returns true if the supplied object has the property at the specified path.

source

Examining Client API Response

OpenAPI.Clients.ApiResponse — Type
ApiResponse

Represents the HTTP API response from the server. This is returned as the second return value from all API calls.

Properties available:

  • status: the HTTP status code
  • message: the HTTP status message
  • headers: the HTTP headers
  • raw: the raw response ( as a Downloads.Response object)
source
OpenAPI.Clients.is_longpoll_timeout — Function
is_longpoll_timeout(ex::Exception)

Examine the supplied exception and return true if the reason is timeout of a long polling request. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

source
OpenAPI.Clients.is_request_interrupted — Function
is_request_interrupted(ex::Exception)

Examine the supplied exception and return true if the reason is that the request was interrupted. If the exception is a nested exception of type CompositeException or TaskFailedException, then navigates through the nested exception values to examine the leaves.

source
OpenAPI.Clients.storefile — Function
storefile(api_call::Function;
     folder::AbstractString = pwd(),
     rename_file::String="",
     )::Tuple{Any,ApiResponse,String}
@@ -54,7 +54,7 @@
 - `folder`: Location to store file, defaults to `pwd()`.
 - `filename`: Use this filename, overrides any filename that may be there in the `Content-Disposition` header.
 
-Returns: (result, http_response, file_path)
source

Server

The server code is generated as a package. It contains API stubs and validations of API inputs. It requires the caller to have implemented the APIs, the signatures of which are provided in the generated package module docstring.

Refer to the User Guide section for mode details of the API that is generated.

Tools

OpenAPI.openapi_generator — Function
openapi_generator(; port=8080, use_sudo=false)

Start an OpenAPI Generator Online container. Returns the URL of the OpenAPI Generator.

Optional arguments:

  • port: The port to use for the OpenAPI Generator. Defaults to 8080.
  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
OpenAPI.stop_openapi_generator — Function
stop_openapi_generator(; use_sudo=false)

Stop and remove the OpenAPI Generator container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.generate — Function
generate(
+Returns: (result, http_response, file_path)
source

Server

The server code is generated as a package. It contains API stubs and validations of API inputs. It requires the caller to have implemented the APIs, the signatures of which are provided in the generated package module docstring.

Refer to the User Guide section for mode details of the API that is generated.

Tools

OpenAPI.openapi_generator — Function
openapi_generator(; port=8080, use_sudo=false)

Start an OpenAPI Generator Online container. Returns the URL of the OpenAPI Generator.

Optional arguments:

  • port: The port to use for the OpenAPI Generator. Defaults to 8080.
  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
OpenAPI.stop_openapi_generator — Function
stop_openapi_generator(; use_sudo=false)

Stop and remove the OpenAPI Generator container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.generate — Function
generate(
     spec::Dict{String,Any};
     type::Symbol=:client,
     package_name::AbstractString="APIClient",
@@ -62,8 +62,8 @@
     export_operations::Bool=false,
     output_dir::AbstractString="",
     generator_host::AbstractString=GeneratorHost.Local
-)

Generate client or server code from an OpenAPI spec using the OpenAPI Generator. The OpenAPI Generator must be running at the specified generator_host.

Returns the path to the generated code.

Optional arguments:

  • type: The type of code to generate. Must be :client or :server. Defaults to :client.
  • package_name: The name of the package to generate. Defaults to "APIClient".
  • export_models: Whether to export models. Defaults to false.
  • export_operations: Whether to export operations. Defaults to false.
  • output_dir: The directory to save the generated code. Defaults to a temporary directory. Directory will be created if it does not exist.
  • generator_host: The host of the OpenAPI Generator. Defaults to GeneratorHost.Local. Other possible values are GeneratorHost.OpenAPIGeneratorTech.Stable or GeneratorHost.OpenAPIGeneratorTech.Master, which point to the service hosted by OpenAPI org. It can also be any other URL where the OpenAPI Generator is running.

A locally hosted generator service is preferred by default for privacy reasons. Use openapi_generator to start a local container. Use stop_openapi_generator to stop the local generator service after use.

source
OpenAPI.swagger_ui — Function
swagger_ui(spec; port=8080, use_sudo=false)
-swagger_ui(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger UI container for the given OpenAPI spec file. Returns the URL of the Swagger UI.

Optional arguments:

  • port: The port to use for the Swagger UI. Defaults to 8080.
  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
OpenAPI.stop_swagger_ui — Function
stop_swagger_ui(; use_sudo=false)

Stop and remove the Swagger UI container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.swagger_editor — Function
swagger_editor(; port=8080, use_sudo=false)
+)

Generate client or server code from an OpenAPI spec using the OpenAPI Generator. The OpenAPI Generator must be running at the specified generator_host.

Returns the path to the generated code.

Optional arguments:

  • type: The type of code to generate. Must be :client or :server. Defaults to :client.
  • package_name: The name of the package to generate. Defaults to "APIClient".
  • export_models: Whether to export models. Defaults to false.
  • export_operations: Whether to export operations. Defaults to false.
  • output_dir: The directory to save the generated code. Defaults to a temporary directory. Directory will be created if it does not exist.
  • generator_host: The host of the OpenAPI Generator. Defaults to GeneratorHost.Local. Other possible values are GeneratorHost.OpenAPIGeneratorTech.Stable or GeneratorHost.OpenAPIGeneratorTech.Master, which point to the service hosted by OpenAPI org. It can also be any other URL where the OpenAPI Generator is running.

A locally hosted generator service is preferred by default for privacy reasons. Use openapi_generator to start a local container. Use stop_openapi_generator to stop the local generator service after use.

source
OpenAPI.swagger_ui — Function
swagger_ui(spec; port=8080, use_sudo=false)
+swagger_ui(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger UI container for the given OpenAPI spec file. Returns the URL of the Swagger UI.

Optional arguments:

  • port: The port to use for the Swagger UI. Defaults to 8080.
  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
OpenAPI.stop_swagger_ui — Function
stop_swagger_ui(; use_sudo=false)

Stop and remove the Swagger UI container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.swagger_editor — Function
swagger_editor(; port=8080, use_sudo=false)
 swagger_editor(spec; port=8080, use_sudo=false)
-swagger_editor(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger Editor container with an optional OpenAPI spec file. Returns the URL of the Swagger Editor.

Optional arguments:

  • port: The port to use for the Swagger Editor. Defaults to 8080.
  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
OpenAPI.stop_swagger_editor — Function
stop_swagger_editor(; use_sudo=false)

Stop and remove the Swagger Editor container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.lint — Function
lint(spec; use_sudo=false)
-lint(spec_dir, spec_file; use_sudo=false)

Lint an OpenAPI spec file using Spectral.

Optional arguments:

  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
+swagger_editor(spec_dir, spec_file; port=8080, use_sudo=false)

Start a Swagger Editor container with an optional OpenAPI spec file. Returns the URL of the Swagger Editor.

Optional arguments:

source
OpenAPI.stop_swagger_editor — Function
stop_swagger_editor(; use_sudo=false)

Stop and remove the Swagger Editor container, if it is running. Returns true if the container was stopped and removed, false otherwise.

source
OpenAPI.lint — Function
lint(spec; use_sudo=false)
+lint(spec_dir, spec_file; use_sudo=false)

Lint an OpenAPI spec file using Spectral.

Optional arguments:

  • use_sudo: Whether to use sudo to run Docker commands. Defaults to false.
source
diff --git a/dev/search/index.html b/dev/search/index.html index 990029b..2d60692 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · OpenAPI.jl

Loading search...

    +Search · OpenAPI.jl

    Loading search...

      diff --git a/dev/todo/index.html b/dev/todo/index.html index 7fdf3fc..3e1d5fb 100644 --- a/dev/todo/index.html +++ b/dev/todo/index.html @@ -1,2 +1,2 @@ -TODO · OpenAPI.jl
      Edit on GitHub
      +TODO · OpenAPI.jl
      Edit on GitHub
      diff --git a/dev/tools/index.html b/dev/tools/index.html index 9a18201..df1b146 100644 --- a/dev/tools/index.html +++ b/dev/tools/index.html @@ -61,4 +61,4 @@ spec_dir::AbstractString; # folder containing the specification file spec_file::AbstractString; # the specification file use_sudo::Bool=false # whether to use sudo while invoking docker -) +) diff --git a/dev/userguide/index.html b/dev/userguide/index.html index 67a7aa0..3799f38 100644 --- a/dev/userguide/index.html +++ b/dev/userguide/index.html @@ -33,4 +33,4 @@ chunk_reader_type::Union{Nothing,Type{<:AbstractChunkReader}}=nothing, verbose::Union{Bool,Function}=false, )

      Where:

      The pre_request_hook must provide the following two implementations:

      The chunk_reader_type can be one of LineChunkReader, JSONChunkReader or RFC7464ChunkReader. If not specified, then the type is automatically determined based on the return type of the API call. Refer to the Streaming Responses section for more details.

      The verbose option can be one of:

      In case of any errors an instance of ApiException is thrown. It has the following fields:

      An API call involves the following steps:

      Server APIs

      The server code is generated as a package. It contains API stubs and validations of API inputs. It requires the caller to have implemented the APIs, the signatures of which are provided in the generated package module docstring.

      A register function is made available that when provided with a Router instance, registers handlers for all the APIs.

      register(router, impl; path_prefix="", optional_middlewares...) -> HTTP.Router

      Paramerets:

      Optional parameters:

      Optional middlewares can be one or more of:

      The order in which middlewares are invoked is: init |> read |> pre_validation |> validate |> pre_invoke |> invoke |> post_invoke

      Responses

      The server APIs can return the Julia type that is specified in the OpenAPI specification. The response is serialized as JSON and sent back to the client. The default HTTP response code used in this case is 200.

      To return a custom HTTP response code, the server API can return a HTTP.Response instance directly. The OpenAPI package provides a overridden constructor for HTTP.Response that takes the desired HTTP code and the Julia struct that needs to be serialized as JSON and sent back to the client. It also sets the Content-Type header to application/json.

      HTTP.Response(code::Integer, o::APIModel)

      Structured error messages can also be returned in similar fashion. Any uncaught exception thrown by the server API is caught and converted into a HTTP.Response instance with the HTTP code set to 500 and the exception message as the response body.

      Streaming Responses

      Some OpenAPI implementations implement streaming of responses by sending more than one items in the response, each of which is of the type declared as the return type in the specification. E.g. the Twitter OpenAPI specification that keeps sending tweets in JSON like this forever:

      {"data":{"id":"1800000000000000000","text":"mmm i like a sandwich"},"matching_rules":[{"id":1800000000000000000,"tag":"\"sandwich\""}]}
-{"data":{"id":"1800000000000000001","text":"lets have a sandwich"},"matching_rules":[{"id":1800000000000000001,"tag":"\"sandwich\""}]}

      OpenAPI.jl handles such responses through "chunk readers" which are engaged only with the streaming API endpoints. There can be multiple implementations of chunk readers, each of which must be of type AbstractChunkReader. The following are the chunk readers provided, each with a different chunk detection strategy. They are selected based on some heuristics based on the response data type.

      The OpenAPI.Clients.Client and OpenAPI.Clients.Ctx constructors take an additional chunk_reader_type keyword parameter. This can be one of OpenAPI.Clients.LineChunkReader, OpenAPI.Clients.JSONChunkReader or OpenAPI.Clients.RFC7464ChunkReader. If not specified, then the type is automatically determined as described above.

      +{"data":{"id":"1800000000000000001","text":"lets have a sandwich"},"matching_rules":[{"id":1800000000000000001,"tag":"\"sandwich\""}]}

      OpenAPI.jl handles such responses through "chunk readers" which are engaged only with the streaming API endpoints. There can be multiple implementations of chunk readers, each of which must be of type AbstractChunkReader. The following are the chunk readers provided, each with a different chunk detection strategy. They are selected based on some heuristics based on the response data type.

      The OpenAPI.Clients.Client and OpenAPI.Clients.Ctx constructors take an additional chunk_reader_type keyword parameter. This can be one of OpenAPI.Clients.LineChunkReader, OpenAPI.Clients.JSONChunkReader or OpenAPI.Clients.RFC7464ChunkReader. If not specified, then the type is automatically determined as described above.