Skip to content

Commit 585580f

Browse files
tanmaykmtanmaykm
authored
add docs using documenter (#56)
Moved existing docs from readme, and added few more. Using documenter to prepare and publish docs.
1 parent c0637d4 commit 585580f

File tree

11 files changed

+514
-334
lines changed

11 files changed

+514
-334
lines changed

‎.github/workflows/ci.yml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,14 @@ jobs:
4040
- uses: codecov/codecov-action@v1
4141
with:
4242
file: lcov.info
43+
docs:
44+
name: Documentation
45+
runs-on: ubuntu-latest
46+
permissions:
47+
contents: write
48+
steps:
49+
- uses: actions/checkout@v2
50+
- uses: julia-actions/julia-buildpkg@v1
51+
- uses: julia-actions/julia-docdeploy@v1
52+
env:
53+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎README.md

Lines changed: 10 additions & 329 deletions
Large diffs are not rendered by default.

‎docs/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
build

‎docs/Project.toml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
4+
[compat]
5+
Documenter = "0.27"

‎docs/make.jl

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import Pkg
2+
Pkg.add("Documenter")
3+
4+
using Documenter
5+
using OpenAPI
6+
7+
makedocs(
8+
sitename = "OpenAPI.jl",
9+
format = Documenter.HTML(
10+
prettyurls = get(ENV, "CI", nothing) == "true"
11+
),
12+
pages = [
13+
"Home" => "index.md",
14+
"User Guide" => "userguide.md",
15+
"Reference" => "reference.md",
16+
"Tools" => "tools.md",
17+
"TODO" => "todo.md",
18+
],
19+
)
20+
21+
deploydocs(
22+
repo = "github.com/JuliaComputing/OpenAPI.jl.git",
23+
push_preview = true,
24+
)

‎docs/src/index.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# OpenAPI.jl
2+
3+
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.
4+
5+
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.
6+
7+
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.
8+
9+
## Migrating from Swagger.jl
10+
11+
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.
12+

‎docs/src/reference.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
```@contents
2+
Pages = ["reference.md"]
3+
Depth = 3
4+
```
5+
6+
```@meta
7+
CurrentModule = OpenAPI
8+
```
9+
10+
# API Reference
11+
12+
## Client
13+
14+
```@docs
15+
Clients.Client
16+
Clients.set_user_agent
17+
Clients.set_cookie
18+
Clients.set_header
19+
Clients.set_timeout
20+
```
21+
22+
## Examining Models
23+
24+
```@docs
25+
hasproperty
26+
getproperty
27+
setproperty!
28+
Clients.getpropertyat
29+
Clients.haspropertyat
30+
```
31+
32+
## Examining Client API Response
33+
34+
```@docs
35+
Clients.ApiResponse
36+
```
37+
38+
```@docs
39+
Clients.is_longpoll_timeout
40+
```
41+
42+
```@docs
43+
Clients.is_request_interrupted
44+
```
45+
46+
```@docs
47+
Clients.storefile
48+
```
49+
50+
## Server
51+
52+
The server code is generated as a package. It contains API stubs and validations of API inputs. It requires the caller to
53+
have implemented the APIs, the signatures of which are provided in the generated package module docstring.
54+
55+
Refer to the User Guide section for mode details of the API that is generated.
56+
57+
## Tools
58+
59+
```@docs
60+
swagger_ui
61+
stop_swagger_ui
62+
swagger_editor
63+
stop_swagger_editor
64+
lint
65+
```

‎docs/src/todo.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# TODO
2+
3+
Not all OpenAPI features are supported yet, e.g.:
4+
- [`not`](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)
5+
- [inheritance and polymorphism](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/)
6+
- [some of the JSON schema keywords](https://swagger.io/docs/specification/data-models/keywords/)
7+
- some [subtler data types](https://swagger.io/docs/specification/data-models/data-types/)
8+
- native representaion of some of the string formats, e.g. uuid, url
9+
- read-only and write-only properties
10+
- better enum support
11+
- authentication schemes
12+
- [`deepObject`](https://swagger.io/docs/specification/serialization/)s in query parameters
13+
14+
There could be more unsupported features than what is listed above.

‎docs/src/tools.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Tools
2+
3+
## Swagger UI
4+
5+
[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.
6+
7+
Use `OpenAPI.swagger_ui` to open Swagger UI. It uses the standard `swaggerapi/swagger-ui` docker image and requires docker engine to be installed.
8+
9+
```julia
10+
# specify a specification file to start with
11+
OpenAPI.swagger_ui(
12+
spec::AbstractString; # the OpenAPI specification to use
13+
port::Int=8080, # port to use
14+
use_sudo::Bool=false # whether to use sudo while invoking docker
15+
)
16+
17+
# specify a folder and specification file name to start with
18+
OpenAPI.swagger_ui(
19+
spec_dir::AbstractString; # folder containing the specification file
20+
spec_file::AbstractString; # the specification file
21+
port::Int=8080, # port to use
22+
use_sudo::Bool=false # whether to use sudo while invoking docker
23+
)
24+
```
25+
26+
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.
27+
28+
```julia
29+
DefaultApplication.open(OpenAPI.swagger_ui("/my/openapi/spec.json"))
30+
```
31+
32+
To stop the Swagger UI container, use `OpenAPI.stop_swagger_ui`.
33+
34+
```julia
35+
OpenAPI.stop_swagger_ui(;
36+
use_sudo::Bool=false # whether to use sudo while invoking docker
37+
)
38+
```
39+
40+
## Swagger Editor
41+
42+
[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.
43+
44+
Use `OpenAPI.swagger_editor` to open Swagger Editor. It uses the standard `swaggerapi/swagger-editor` docker image and requires docker engine to be installed.
45+
46+
```julia
47+
# specify a specification file to start with
48+
OpenAPI.swagger_editor(
49+
spec::AbstractString; # the OpenAPI specification to use
50+
port::Int=8080, # port to use
51+
use_sudo::Bool=false # whether to use sudo while invoking docker
52+
)
53+
54+
# specify a folder and specification file name to start with
55+
OpenAPI.swagger_editor(
56+
spec_dir::AbstractString; # folder containing the specification file
57+
spec_file::AbstractString; # the specification file
58+
port::Int=8080, # port to use
59+
use_sudo::Bool=false # whether to use sudo while invoking docker
60+
)
61+
62+
# start without specifying any initial specification file
63+
OpenAPI.swagger_editor(
64+
port::Int=8080, # port to use
65+
use_sudo::Bool=false # whether to use sudo while invoking docker
66+
)
67+
```
68+
69+
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.
70+
71+
```julia
72+
DefaultApplication.open(OpenAPI.swagger_editor("/my/openapi/spec.json"))
73+
```
74+
75+
To stop the Swagger Editor container, use `OpenAPI.stop_swagger_editor`.
76+
77+
```julia
78+
OpenAPI.stop_swagger_editor(;
79+
use_sudo::Bool=false # whether to use sudo while invoking docker
80+
)
81+
```
82+
83+
## Spectral Linter
84+
85+
[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.
86+
87+
```julia
88+
# specify a specification file to start with
89+
OpenAPI.lint(
90+
spec::AbstractString; # the OpenAPI specification to use
91+
use_sudo::Bool=false # whether to use sudo while invoking docker
92+
)
93+
94+
# specify a folder and specification file name to start with
95+
OpenAPI.lint(
96+
spec_dir::AbstractString; # folder containing the specification file
97+
spec_file::AbstractString; # the specification file
98+
use_sudo::Bool=false # whether to use sudo while invoking docker
99+
)
100+
```

0 commit comments

Comments
 (0)