swagger_ui_standalone 0.1.4 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +152 -21
  3. data/lib/swagger_ui_standalone/cli.rb +45 -5
  4. data/lib/swagger_ui_standalone/version.rb +1 -1
  5. data/lib/swagger_ui_standalone/zipball.rb +4 -5
  6. data/lib/swagger_ui_standalone.rb +3 -2
  7. metadata +5 -5
  8. /data/exe/{swagger-ui-standalone → swagger_ui_standalone} +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 204e56e0b1483c06696d194eac0f9d044cff6cb4139951da590337d8d9c31edf
4
- data.tar.gz: 0c32dcc58d04719103e67954ee17c52e9597870040d49628bdb92fc37a424931
3
+ metadata.gz: 3f9afbe0a8118ee537a0d155bf5f25d262a5ebebcfff54f061d49b17fd79fbf2
4
+ data.tar.gz: 3f46be82ad2730a629d6f23225689bcc215e31af7e7d2c9f5588081eac8c919d
5
5
  SHA512:
6
- metadata.gz: 1221c9fae1855e171a0a3b40fa4af5bb4fb43f848aac13a3eabcef03eafc4bd7056d801456c0dcd36eeb792e977fca5f1654cb856bc0b7c42b9cff7463c22c55
7
- data.tar.gz: e9b98922dde9202d38c5a2066704e1c9f70f27a018dbcda217faea627e5ea695f04d14d59c3714e69a4d0e09a4c6bceaea9a460730c4f156d527942854d04de9
6
+ metadata.gz: 992241f55e77a1819c8b8d1634560fcedc493de2b7f22db296b8600c63b7bd3f0803fa59d2fb53a19bf6dfa0249159f7d8685b06279a4dc4dddfe6758d48d905
7
+ data.tar.gz: 29e12b0f7b0f3c1a92555761691753bcd0484d6635360b4a2cb552abe94c06814093158db528cf148bd552845280dbaa4eb6959e450101b04c784c03af1c52a1
data/README.md CHANGED
@@ -1,43 +1,174 @@
1
- # SwaggerUIStandalone
1
+ <div align="center">
2
2
 
3
- TODO: Delete this and the text below, and describe your gem
3
+ # Swagger UI Standalone
4
4
 
5
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/swagger_ui_standalone`. To experiment with that code, run `bin/console` for an interactive prompt.
5
+ [![Gem Version](https://img.shields.io/gem/v/swagger_ui_standalone)](https://badge.fury.io/rb/swagger_ui_standalone)
6
+ [![Ruby](https://github.com/typisttech/swagger_ui_standalone/actions/workflows/main.yml/badge.svg)](https://github.com/typisttech/swagger_ui_standalone/actions/workflows/main.yml)
7
+ [![License](https://img.shields.io/github/license/typisttech/swagger_ui_standalone.svg)](https://github.com/typisttech/swagger_ui_standalone/blob/master/LICENSE.txt)
8
+ [![Follow @TangRufus on X](https://img.shields.io/badge/Follow-TangRufus-15202B?logo=x&logoColor=white)](https://x.com/tangrufus)
9
+ [![Follow @TangRufus.com on Bluesky](https://img.shields.io/badge/Bluesky-TangRufus.com-blue?logo=bluesky)](https://bsky.app/profile/tangrufus.com)
10
+ [![Sponsor @TangRufus via GitHub](https://img.shields.io/badge/Sponsor-TangRufus-EA4AAA?logo=githubsponsors)](https://github.com/sponsors/tangrufus)
11
+ [![Hire Typist Tech](https://img.shields.io/badge/Hire-Typist%20Tech-778899)](https://typist.tech/contact/)
6
12
 
7
- ## Installation
13
+ <p>
14
+ <strong>Generate standalone static Swagger UI sites from OpenAPI specifications.</strong>
15
+ <br>
16
+ <br>
17
+ Built with ♥ by <a href="https://typist.tech/">Typist Tech</a>
18
+ </p>
8
19
 
9
- TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
20
+ </div>
10
21
 
11
- Install the gem and add to the application's Gemfile by executing:
22
+ ---
23
+
24
+ ## Quick Start
12
25
 
13
26
  ```bash
14
- bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
27
+ # Install the gem
28
+ gem install swagger_ui_standalone
29
+
30
+ # Prepare some custom files
31
+ mkdir custom
32
+
33
+ ## Download some OpenAPI specifications
34
+ wget https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml -O custom/github.yaml
35
+ wget https://validator.swagger.io/validator/openapi.json -O custom/validator.yaml
36
+
37
+ ## Make a disallow all robots.txt file
38
+ cat > custom/robots.txt <<EOF
39
+ User-agent: *
40
+ Disallow: /
41
+ EOF
42
+
43
+ ## Create custom swagger-initializer.js to override the default file
44
+ cat > custom/swagger-initializer.js <<EOF
45
+ window.onload = function() {
46
+ window.ui = SwaggerUIBundle({
47
+ urls: [
48
+ {name: "GitHub", url: "github.yaml"},
49
+ {name: "Validator", url: "validator.yaml"},
50
+ {name: "Petstore (External)", url: "https://petstore.swagger.io/v2/swagger.json"},
51
+ ],
52
+ dom_id: '#swagger-ui',
53
+ deepLinking: true,
54
+ presets: [
55
+ SwaggerUIBundle.presets.apis,
56
+ SwaggerUIStandalonePreset
57
+ ],
58
+ plugins: [
59
+ SwaggerUIBundle.plugins.DownloadUrl
60
+ ],
61
+ layout: "StandaloneLayout"
62
+ });
63
+ };
64
+ EOF
65
+
66
+ # Generate a standalone static Swagger UI site into the output directory
67
+ swagger_ui_standalone generate --custom custom --output output
15
68
  ```
16
69
 
17
- If bundler is not being used to manage dependencies, install the gem by executing:
18
-
19
- ```bash
20
- gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
70
+ The `generate` command downloads the latest release of Swagger UI from GitHub and copy the `dist` directory to the `output` directory.
71
+ Then, the `custom` directory is copied as is, so you can add or overwrite files in the `output` directory.
72
+
73
+ ```console
74
+ $ tree custom output
75
+ custom
76
+ ├── github.yaml
77
+ ├── robots.txt
78
+ ├── swagger-initializer.js
79
+ └── validator.yaml
80
+ output
81
+ ├── favicon-16x16.png
82
+ ├── favicon-32x32.png
83
+ ├── github.yaml
84
+ ├── index.css
85
+ ├── index.html
86
+ ├── oauth2-redirect.html
87
+ ├── robots.txt
88
+ ├── swagger-initializer.js
89
+ ├── swagger-ui-bundle.js
90
+ ├── swagger-ui-bundle.js.map
91
+ ├── swagger-ui-es-bundle-core.js
92
+ ├── swagger-ui-es-bundle-core.js.map
93
+ ├── swagger-ui-es-bundle.js
94
+ ├── swagger-ui-es-bundle.js.map
95
+ ├── swagger-ui-standalone-preset.js
96
+ ├── swagger-ui-standalone-preset.js.map
97
+ ├── swagger-ui.css
98
+ ├── swagger-ui.css.map
99
+ ├── swagger-ui.js
100
+ ├── swagger-ui.js.map
101
+ └── validator.yaml
102
+
103
+ # Start a local web server to serve the static site with webrick
104
+ # See https://gist.github.com/willurd/5720255 for alternatives
105
+ $ gem install webrick
106
+ $ ruby -run -ehttpd output -p8000
21
107
  ```
22
108
 
23
109
  ## Usage
24
110
 
25
- TODO: Write usage instructions here
111
+ ### `generate`
112
+
113
+ ```console
114
+ $ swagger_ui_standalone help generate
115
+ Usage:
116
+ swagger_ui_standalone generate [options] --custom=DIRECTORY --output=DIRECTORY
26
117
 
27
- ## Development
118
+ Options:
119
+ --custom=DIRECTORY # Path to the directory containing custom files, which will be copied to the output directory
120
+ --output=DIRECTORY # Where to write the generated files
121
+ [--repo=OWNER/REPO] # GitHub repository to download in the format <owner/repo>
122
+ # Default: swagger-api/swagger-ui
123
+ [--ref=TAG|BRANCH|SHA] # Git reference to download (can be a tag, branch or commit SHA). Omit to use the latest release
124
+ [--force] # Overwrite files that already exist
28
125
 
29
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
126
+ Generate standalone static Swagger UI
127
+ ```
128
+
129
+ ### `download`
130
+
131
+ ```console
132
+ $ swagger_ui_standalone help download
133
+ Usage:
134
+ swagger_ui_standalone download [options] --output=DIRECTORY
135
+
136
+ Options:
137
+ --output=DIRECTORY # Where to write the generated files
138
+ [--repo=OWNER/REPO] # GitHub repository to download in the format <owner/repo>
139
+ # Default: swagger-api/swagger-ui
140
+ [--ref=TAG|BRANCH|SHA] # Git reference to download (can be a tag, branch or commit SHA). Omit to use the latest release
141
+ [--force] # Overwrite files that already exist
142
+
143
+ Download standalone static Swagger UI source code
144
+ ```
145
+
146
+ ## Installation
147
+
148
+ Install the gem and add to the application's Gemfile by executing:
149
+
150
+ ```bash
151
+ bundle add swagger_ui_standalone
152
+ ```
153
+
154
+ If bundler is not being used to manage dependencies, install the gem by executing:
155
+
156
+ ```bash
157
+ gem install swagger_ui_standalone
158
+ ```
30
159
 
31
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
160
+ ## Credits
32
161
 
33
- ## Contributing
162
+ [`Swagger UI Standalone`](https://github.com/typisttech/swagger_ui_standalone) is a [Typist Tech](https://typist.tech) project and
163
+ maintained by [Tang Rufus](https://x.com/TangRufus), freelance developer [for hire](https://typist.tech/contact/).
34
164
 
35
- Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/swagger_ui_standalone. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/swagger_ui_standalone/blob/main/CODE_OF_CONDUCT.md).
165
+ Full list of contributors can be found [on GitHub](https://github.com/typisttech/swagger_ui_standalone/graphs/contributors).
36
166
 
37
- ## License
167
+ ## Copyright and License
38
168
 
39
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
169
+ This project is a [free software](https://www.gnu.org/philosophy/free-sw.en.html) distributed under the terms of
170
+ the MIT license. For the full license, see [LICENSE](./LICENSE.txt).
40
171
 
41
- ## Code of Conduct
172
+ ## Contribute
42
173
 
43
- Everyone interacting in the SwaggerUIStandalone project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/swagger_ui_standalone/blob/main/CODE_OF_CONDUCT.md).
174
+ Feedbacks / bug reports / pull requests are welcome.
data/lib/swagger_ui_standalone/cli.rb CHANGED
@@ -5,13 +5,25 @@ require_relative "../swagger_ui_standalone"
5
5
 
6
6
  module SwaggerUIStandalone
7
7
  class CLI < Thor
8
+ include Thor::Actions
9
+
8
10
  def self.exit_on_failure?
9
11
  true
10
12
  end
11
13
 
12
- def self.define_downloadable_options
14
+ no_commands do
15
+ def copy_directory(source, destination, config = {})
16
+ absolute_source = File.absolute_path(source)
17
+
18
+ self.class.source_root File.dirname(absolute_source)
19
+ @source_paths = nil
20
+
21
+ directory File.basename(absolute_source), destination, config
22
+ end
23
+ end
24
+
25
+ def self.define_download_options
13
26
  option :output,
14
- aliases: ["-o", "--out"],
15
27
  type: :string,
16
28
  desc: "Where to write the generated files",
17
29
  banner: "DIRECTORY",
@@ -25,13 +37,41 @@ module SwaggerUIStandalone
25
37
  type: :string,
26
38
  banner: "TAG|BRANCH|SHA",
27
39
  desc: "Git reference to download (can be a tag, branch or commit SHA). Omit to use the latest release"
40
+ option :force,
41
+ type: :boolean,
42
+ desc: "Overwrite files that already exist"
28
43
  end
29
44
 
30
- desc "download [options]", "Download standalone static SwaggerUI source code"
31
- define_downloadable_options
45
+ desc "generate [options]", "Generate standalone static Swagger UI"
46
+ option :custom,
47
+ type: :string,
48
+ desc: "Path to the directory containing custom files, which will be copied to the output directory",
49
+ banner: "DIRECTORY",
50
+ required: true
51
+ define_download_options
52
+
53
+ def generate
54
+ Dir.mktmpdir do |tmp_dir|
55
+ # We only want the dist directory.
56
+ tmp_dist_dir = File.join(tmp_dir, DIST_DIR)
57
+
58
+ SwaggerUIStandalone.download_source tmp_dir, repo: options.repo, ref: options.ref
59
+ copy_directory options[:custom], tmp_dist_dir, recursive: true, force: true, verbose: false
60
+
61
+ copy_directory tmp_dist_dir, options.output, recursive: true, force: options.force, verbose: true
62
+ end
63
+ end
64
+
65
+ desc "download [options]", "Download standalone static Swagger UI source code"
66
+ define_download_options
32
67
 
33
68
  def download
34
- SwaggerUIStandalone.download_source options.output, repo: options.repo, ref: options.ref
69
+ Dir.mktmpdir do |tmp_dir|
70
+ SwaggerUIStandalone.download_source tmp_dir, repo: options.repo, ref: options.ref
71
+
72
+ # We only want the dist directory.
73
+ copy_directory File.join(tmp_dir, DIST_DIR), options.output, recursive: true, force: options.force, verbose: true
74
+ end
35
75
  end
36
76
  end
37
77
  end
data/lib/swagger_ui_standalone/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module SwaggerUIStandalone
4
- VERSION = "0.1.4"
4
+ VERSION = "0.2.1"
5
5
  end
data/lib/swagger_ui_standalone/zipball.rb CHANGED
@@ -4,13 +4,12 @@ require "zip"
4
4
 
5
5
  module SwaggerUIStandalone
6
6
  module Zipball
7
- def extract(path, content_directory:, destination_directory:)
8
- pattern = "*/#{content_directory}/**"
9
- prefix = "#{content_directory}/"
10
-
7
+ def extract(path, pattern:, destination_directory:)
11
8
  Zip::File.open(path) do |zip_file|
12
9
  zip_file.glob(pattern).each do |entry|
13
- i = entry.name.index(prefix) + prefix.length
10
+ # Remove the leading directory from the entry name
11
+ # e.g. "swagger-api-swagger-ui-3c4e5b7/dist/index.html" --> "dist/index.html"
12
+ i = entry.name.index("/") + 1
14
13
  entry_path = entry.name[i..]
15
14
 
16
15
  full_destination_path = File.join(destination_directory, entry_path)
data/lib/swagger_ui_standalone.rb CHANGED
@@ -11,10 +11,11 @@ module SwaggerUIStandalone
11
11
  extend Zipball
12
12
 
13
13
  SOURCE_REPO = "swagger-api/swagger-ui"
14
+ DIST_DIR = "dist"
14
15
 
15
- def self.download_source(output_directory, repo: SOURCE_REPO, ref: nil, content_directory: "dist")
16
+ def self.download_source(output_directory, repo: SOURCE_REPO, ref: nil, pattern: "*/#{DIST_DIR}/**")
16
17
  url = ref.nil? ? latest_release_archive_link(repo) : archive_link(repo, ref)
17
18
  zipball = download url
18
- extract zipball, content_directory:, destination_directory: output_directory
19
+ extract zipball, pattern:, destination_directory: output_directory
19
20
  end
20
21
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: swagger_ui_standalone
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Typist Tech Limited
@@ -84,7 +84,7 @@ email:
84
84
  - opensource+swagger_ui_standalone@typist.tech
85
85
  - tangrufus@gmail.com
86
86
  executables:
87
- - swagger-ui-standalone
87
+ - swagger_ui_standalone
88
88
  extensions: []
89
89
  extra_rdoc_files: []
90
90
  files:
@@ -95,7 +95,7 @@ files:
95
95
  - LICENSE.txt
96
96
  - README.md
97
97
  - Rakefile
98
- - exe/swagger-ui-standalone
98
+ - exe/swagger_ui_standalone
99
99
  - lib/swagger_ui_standalone.rb
100
100
  - lib/swagger_ui_standalone/cli.rb
101
101
  - lib/swagger_ui_standalone/github.rb
@@ -121,7 +121,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
121
121
  requirements:
122
122
  - - ">="
123
123
  - !ruby/object:Gem::Version
124
- version: 3.1.0
124
+ version: 3.2.0
125
125
  required_rubygems_version: !ruby/object:Gem::Requirement
126
126
  requirements:
127
127
  - - ">="
@@ -130,5 +130,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
130
130
  requirements: []
131
131
  rubygems_version: 3.6.7
132
132
  specification_version: 4
133
- summary: Generate standalone static SwaggerUI sites from OpenAPI specifications.
133
+ summary: Generate standalone static Swagger UI sites from OpenAPI specifications.
134
134
  test_files: []