add docs using documenter (#56)

Moved existing docs from readme, and added few more.
Using documenter to prepare and publish docs.

.github/workflows/ci.yml

@@ -40,3 +40,14 @@ jobs:
  - uses: codecov/codecov-action@v1
  with:
  file: lcov.info
+ docs:
+ name: Documentation
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v2
+ - uses: julia-actions/julia-buildpkg@v1
+ - uses: julia-actions/julia-docdeploy@v1
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/.gitignore

@@ -0,0 +1 @@
+build

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"

docs/make.jl

@@ -0,0 +1,24 @@
+import Pkg
+Pkg.add("Documenter")
+
+using Documenter
+using OpenAPI
+
+makedocs(
+ sitename = "OpenAPI.jl",
+ format = Documenter.HTML(
+ prettyurls = get(ENV, "CI", nothing) == "true"
+ ),
+ pages = [
+ "Home" => "index.md",
+ "User Guide" => "userguide.md",
+ "Reference" => "reference.md",
+ "Tools" => "tools.md",
+ "TODO" => "todo.md",
+ ],
+)
+
+deploydocs(
+ repo = "github.com/JuliaComputing/OpenAPI.jl.git",
+ push_preview = true,
+)

docs/src/index.md

@@ -0,0 +1,12 @@
+# OpenAPI.jl
+
+This is the Julia library needed along with code generated by the [OpenAPI generator](https://openapi-generator.tech/) 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](https://github.com/OAI/OpenAPI-Specification) 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](https://github.com/JuliaComputing/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.
+

docs/src/reference.md

@@ -0,0 +1,65 @@
+```@contents
+Pages = ["reference.md"]
+Depth = 3
+```
+
+```@meta
+CurrentModule = OpenAPI
+```
+
+# API Reference
+
+## Client
+
+```@docs
+Clients.Client
+Clients.set_user_agent
+Clients.set_cookie
+Clients.set_header
+Clients.set_timeout
+```
+
+## Examining Models
+
+```@docs
+hasproperty
+getproperty
+setproperty!
+Clients.getpropertyat
+Clients.haspropertyat
+```
+
+## Examining Client API Response
+
+```@docs
+Clients.ApiResponse
+```
+
+```@docs
+Clients.is_longpoll_timeout
+```
+
+```@docs
+Clients.is_request_interrupted
+```
+
+```@docs
+Clients.storefile
+```
+
+## 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
+
+```@docs
+swagger_ui
+stop_swagger_ui
+swagger_editor
+stop_swagger_editor
+lint
+```

docs/src/todo.md

@@ -0,0 +1,14 @@
+# TODO
+
+Not all OpenAPI features are supported yet, e.g.:
+- [`not`](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)
+- [inheritance and polymorphism](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/)
+- [some of the JSON schema keywords](https://swagger.io/docs/specification/data-models/keywords/)
+- some [subtler data types](https://swagger.io/docs/specification/data-models/data-types/)
+ - native representaion of some of the string formats, e.g. uuid, url
+ - read-only and write-only properties
+- better enum support
+- authentication schemes
+- [`deepObject`](https://swagger.io/docs/specification/serialization/)s in query parameters
+
+There could be more unsupported features than what is listed above.

docs/src/tools.md

@@ -0,0 +1,100 @@
+# Tools
+
+## Swagger UI
+
+[Swagger UI](https://swagger.io/tools/swagger-ui/) allows visualization and interaction with the API’s resources without having any of the implementation logic in place. OpenAPI.jl includes convenience methods to launch Swagger UI from Julia.
+
+Use `OpenAPI.swagger_ui` to open Swagger UI. It uses the standard `swaggerapi/swagger-ui` docker image and requires docker engine to be installed.
+
+```julia
+# specify a specification file to start with
+OpenAPI.swagger_ui(
+ spec::AbstractString; # the OpenAPI specification to use
+ port::Int=8080, # port to use 
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+
+# specify a folder and specification file name to start with
+OpenAPI.swagger_ui(
+ spec_dir::AbstractString; # folder containing the specification file
+ spec_file::AbstractString; # the specification file
+ port::Int=8080, # port to use 
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+```
+
+It returns the URL that should be opened in a browser to access the Swagger UI. Combining it with a tool like [DefaultApplication.jl](https://github.com/tpapp/DefaultApplication.jl) can help open a browser tab directly from Julia.
+
+```julia
+DefaultApplication.open(OpenAPI.swagger_ui("/my/openapi/spec.json"))
+```
+
+To stop the Swagger UI container, use `OpenAPI.stop_swagger_ui`.
+
+```julia
+OpenAPI.stop_swagger_ui(;
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+```
+
+## Swagger Editor
+
+[Swagger Editor](https://swagger.io/tools/swagger-editor/) allows editing of OpenAPI specifications and simultaneous visualization and interaction with the API’s resources without having any of the client implementation logic in place. OpenAPI.jl includes convenience methods to launch Swagger Editor from Julia.
+
+Use `OpenAPI.swagger_editor` to open Swagger Editor. It uses the standard `swaggerapi/swagger-editor` docker image and requires docker engine to be installed.
+
+```julia
+# specify a specification file to start with
+OpenAPI.swagger_editor(
+ spec::AbstractString; # the OpenAPI specification to use
+ port::Int=8080, # port to use 
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+
+# specify a folder and specification file name to start with
+OpenAPI.swagger_editor(
+ spec_dir::AbstractString; # folder containing the specification file
+ spec_file::AbstractString; # the specification file
+ port::Int=8080, # port to use 
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+
+# start without specifying any initial specification file
+OpenAPI.swagger_editor(
+ port::Int=8080, # port to use 
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+```
+
+It returns the URL that should be opened in a browser to access the Swagger UI. Combining it with a tool like [DefaultApplication.jl](https://github.com/tpapp/DefaultApplication.jl) can help open a browser tab directly from Julia.
+
+```julia
+DefaultApplication.open(OpenAPI.swagger_editor("/my/openapi/spec.json"))
+```
+
+To stop the Swagger Editor container, use `OpenAPI.stop_swagger_editor`.
+
+```julia
+OpenAPI.stop_swagger_editor(;
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+```
+
+## Spectral Linter
+
+[Spectral](https://stoplight.io/open-source/spectral) is an open-source API style guide enforcer and linter. OpenAPI.jl includes a convenience method to use the Spectral OpenAPI linter from Julia.
+
+```julia
+# specify a specification file to start with
+OpenAPI.lint(
+ spec::AbstractString; # the OpenAPI specification to use
+ use_sudo::Bool=false # whether to use sudo while invoking docker
+)
+
+# specify a folder and specification file name to start with
+OpenAPI.lint(
+ 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
+)
+```