Skip to content

Commit

Permalink
Merge branch 'master' of github.com:icyleaf/swagger
Browse files Browse the repository at this point in the history
icyleaf committed May 6, 2020
2 parents 484e0fe + d0e001e commit cce09eb
Showing 47 changed files with 219 additions and 255 deletions.
25 changes: 15 additions & 10 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
@@ -16,6 +16,9 @@ jobs:
- run:
name: "Crystal Version"
command: crystal version
- run:
name: "Format"
command: crystal tool format --check
- run:
name: "Specs"
command: crystal spec
@@ -25,13 +28,15 @@ jobs:
- deploy:
name: "Upload to gh-page"
command: |
git config --global user.name "$GIT_USER"
git config --global user.email "$GIT_EMAIL"
cd "${DOCS_PATH}"
git init
git remote add origin $GIT_REPO
git fetch origin
if ! [ -z `git branch -r | grep gh-pages` ]; then git reset origin/gh-pages; fi
git add -A .
git commit --allow-empty -m "Updating documents"
git push origin HEAD:gh-pages
if [ "${CIRCLE_BRANCH}" == "master" ] && [ ! "${CIRCLE_PR_NUMBER}" ]; then
git config --global user.name "$GIT_USER"
git config --global user.email "$GIT_EMAIL"
cd "${DOCS_PATH}"
git init
git remote add origin $GIT_REPO
git fetch origin
if ! [ -z `git branch -r | grep gh-pages` ]; then git reset origin/gh-pages; fi
git add -A .
git commit --allow-empty -m "Updating documents"
git push origin HEAD:gh-pages
fi
18 changes: 16 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

> List all changes before release a new version.
## [0.2.0] (2020-02-28)

### Added

- (**breaking-change**) Make operation's `responses` as **REQUIRED**, to match the specification. [#7](https://github.com/icyleaf/swagger/pull/7)
- Update OpenAPI version to 3.0.3. [#11](https://github.com/icyleaf/swagger/pull/11)

### Changed

- Change location to `Swagger::Objects::Parameter::Location` enum. [#5](https://github.com/icyleaf/swagger/pull/5)
- Use JSDelivr CDN source instead of local swagger-ui assets. [#9](https://github.com/icyleaf/swagger/pull/9)
- Move OpenAPI version to `Swagger::Document`. [#10](https://github.com/icyleaf/swagger/pull/10)

## [0.1.1] (2019-12-27)

### Fixed
@@ -19,5 +32,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

- First beta version.

[Unreleased]: https://github.com/icyleaf/halite/compare/v0.1.1...HEAD
[0.1.1]: https://github.com/icyleaf/halite/compare/v0.1.0...v0.1.1
[Unreleased]: https://github.com/icyleaf/swagger/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/icyleaf/swagger/compare/v0.1.1...v0.2.0
[0.1.1]: https://github.com/icyleaf/swagger/compare/v0.1.0...v0.1.1
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -6,7 +6,7 @@
[![Document](https://img.shields.io/badge/document-api-brightgreen.svg)](https://icyleaf.github.io/swagger/)
[![Build Status](https://img.shields.io/circleci/project/github/icyleaf/swagger/master.svg?style=flat)](https://circleci.com/gh/icyleaf/swagger)

Swagger is low-level library which generate output compatible with [Swagger / OpenAPI Spec 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md),
Swagger is a low-level library which generates a document compatible with [Swagger / OpenAPI Spec 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md),
and wrapped many friendly APIs let developer understand and use it easier.

## Installation
16 changes: 8 additions & 8 deletions examples/authorization.cr
Original file line number Diff line number Diff line change
@@ -16,25 +16,25 @@ builder = Swagger::Builder.new(
Swagger::Authorization.api_key(name: "api_key", location: "query", description: "API Key Auth"),
Swagger::Authorization.cookie(name: "JSESSIONID", description: "Cookie Auth"),
Swagger::Authorization.oauth2(grant_type: "implicit", authorization_url: "/oauth/authorize", scopes: {
"read_users" => "Read users in your account",
"write_users" => "modify users in your account"
}, description: "OAuth 2 Auth")
"read_users" => "Read users in your account",
"write_users" => "modify users in your account",
}, description: "OAuth 2 Auth"),
]
)

builder.add(Swagger::Controller.new("Auth", "Authorization", [
Swagger::Action.new("get", "/access_token", "Get Access Token")
Swagger::Action.new("get", "/access_token", [Swagger::Response.new("200", "Success response")], "Get Access Token"),
], external_docs: Swagger::ExternalDocs.new("http://auth.example.com/private_token", "See Details")))

builder.add(Swagger::Controller.new("Users", "User Resources", [
Swagger::Action.new("get", "/users", "List users", parameters: [
Swagger::Action.new("get", "/users", [Swagger::Response.new("200", "Success response")], "List users", parameters: [
Swagger::Parameter.new("page", "query", "integer", "Current page"),
Swagger::Parameter.new("limit", "query", "integer", "How many items to return at one time (max 100)"),
], authorization: true),
Swagger::Action.new("get", "/users/{id}", "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Action.new("get", "/users/{id}", description: "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
], authorization: true)
Swagger::Response.new("404", "Not found user"),
], authorization: true),
]))

Swagger::HTTP::Server.run(builder.built)
24 changes: 12 additions & 12 deletions examples/frameworks/kemal.cr
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@ require "../../src/swagger/http/handler"

user = {
name: "foo",
age: 30,
age: 30,
}

get "/users" do |env|
@@ -20,9 +20,9 @@ get "/users" do |env|

env.response.headers["Content-Type"] = "application/json"
{
total: total_pages,
total: total_pages,
current_page: page,
entry: entry
entry: entry,
}.to_json
end

@@ -31,7 +31,7 @@ post "/users" do |env|
env.response.status_code = 201
{
name: env.params.body["name"],
age: env.params.body["age"],
age: env.params.body["age"],
}.to_json
end

@@ -55,15 +55,15 @@ builder = Swagger::Builder.new(
)

builder.add(Swagger::Controller.new("Users", "User Resources", [
Swagger::Action.new("get", "/users", "List users", parameters: [
Swagger::Action.new("get", "/users", description: "List users", parameters: [
Swagger::Parameter.new("page", "query", "integer", "Current page", default_value: 1),
Swagger::Parameter.new("limit", "query", "integer", "How many items to return at one time (max 100)", default_value: 10),
], responses: [
Swagger::Response.new("200", "Success response"),
]),
Swagger::Action.new("get", "/users/{id}", "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Action.new("get", "/users/{id}", description: "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
Swagger::Response.new("404", "Not found user"),
]),
Swagger::Action.new("post", "/users", "Create a user",
request: Swagger::Request.new([
@@ -72,21 +72,21 @@ builder.add(Swagger::Controller.new("Users", "User Resources", [
], "Form data", "application/x-www-form-urlencoded"),
responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
Swagger::Response.new("404", "Not found user"),
]
),
Swagger::Action.new("delete", "/users/{id}", "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Action.new("delete", "/users/{id}", description: "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
Swagger::Response.new("404", "Not found user"),
]),
]))

builder.add(Swagger::Server.new("http://localhost:{port}/", "Alias Name", [
Swagger::Server::Variable.new("port", "3030", ["3030", "3000"], "API port")
Swagger::Server::Variable.new("port", "3030", ["3030", "3000"], "API port"),
]))

builder.add(Swagger::Server.new("http://0.0.0.0:{port}/", "IP Address", [
Swagger::Server::Variable.new("port", "3030", ["3030", "3000"], "API port")
Swagger::Server::Variable.new("port", "3030", ["3030", "3000"], "API port"),
]))

swagger_api_endpoint = "http://localhost:3030"
26 changes: 13 additions & 13 deletions examples/simple.cr
Original file line number Diff line number Diff line change
@@ -11,23 +11,23 @@ builder = Swagger::Builder.new(
)

builder.add(Swagger::Object.new("User", "object", [
Swagger::Property.new("id", "integer", "int32", example: 1),
Swagger::Property.new("nickname", example: "icyleaf wang"),
Swagger::Property.new("username", example: "icyleaf"),
Swagger::Property.new("email", example: "[email protected]"),
Swagger::Property.new("bio", "Personal bio"),
Swagger::Property.new("id", "integer", "int32", example: 1),
Swagger::Property.new("nickname", example: "icyleaf wang"),
Swagger::Property.new("username", example: "icyleaf"),
Swagger::Property.new("email", example: "[email protected]"),
Swagger::Property.new("bio", "Personal bio"),
]))

builder.add(Swagger::Controller.new("Users", "User Resources", [
Swagger::Action.new("get", "/users", "List users", parameters: [
Swagger::Action.new("get", "/users", [Swagger::Response.new("200", "Success response")], "List users", parameters: [
Swagger::Parameter.new("page", "query", "integer", "Current page", default_value: 1, format: "int32"),
Swagger::Parameter.new("limit", "query", "integer", "How many items to return at one time (max 100)", default_value: 50, format: "int32"),
]),
Swagger::Action.new("get", "/users/{id}", "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Action.new("get", "/users/{id}", description: "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
Swagger::Response.new("404", "Not found user"),
], request: Swagger::Request.new("User")),
Swagger::Action.new("post", "/users", "Create user",
Swagger::Action.new("post", "/users", description: "Create user",
request: Swagger::Request.new([
Swagger::Property.new("username", required: true, description: "The name of user"),
Swagger::Property.new("email", "string", required: true, description: "Email"),
@@ -37,13 +37,13 @@ builder.add(Swagger::Controller.new("Users", "User Resources", [
], "Form data", "application/x-www-form-urlencoded"),
responses: [
Swagger::Response.new("200", "Success response", "User"),
Swagger::Response.new("404", "Not found user")
Swagger::Response.new("404", "Not found user"),
]
),
Swagger::Action.new("get", "/user/{id}", "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Action.new("get", "/user/{id}", description: "Get user by id", parameters: [Swagger::Parameter.new("id", "path")], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
], deprecated: true)
Swagger::Response.new("404", "Not found user"),
], deprecated: true),
]))

builder.add(Swagger::Server.new("http://swagger.dev:{port}/{version}/api", "Development", [
4 changes: 2 additions & 2 deletions shard.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
name: swagger
version: 0.1.1
version: 0.2.0

authors:
- icyleaf <[email protected]>

crystal: 0.32.0
crystal: 0.33.0

license: MIT
4 changes: 4 additions & 0 deletions spec/swagger/action_helper.cr
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
require "spec"
require "../../src/swagger/response"

OK_RESPONSE = [Swagger::Response.new "200", "OK"]
13 changes: 7 additions & 6 deletions spec/swagger/action_spec.cr
Original file line number Diff line number Diff line change
@@ -1,36 +1,37 @@
require "../spec_helper"
require "./action_helper"
require "../../src/swagger/action"

describe Swagger::Action do
describe "#new" do
it "should works" do
raw = Swagger::Action.new("get", "/users")
raw = Swagger::Action.new("get", "/users", OK_RESPONSE)
raw.method.should eq "get"
raw.route.should eq "/users"
raw.responses.should eq OK_RESPONSE
raw.summary.should be_nil
raw.description.should be_nil
raw.parameters.should be_nil
raw.request.should be_nil
raw.responses.should be_nil
raw.authorization.should be_false
raw.deprecated.should be_false
end

it "should stored downcase method" do
raw = Swagger::Action.new("GET", "/users")
raw = Swagger::Action.new("GET", "/users", OK_RESPONSE)
raw.method.should eq "get"
end

{% for ivar in Swagger::Objects::PathItem::METHODS %}
it "should define {{ ivar.id }} method" do
raw = Swagger::Action.new("{{ ivar.id }}", "/users")
raw = Swagger::Action.new("{{ ivar.id }}", "/users", OK_RESPONSE)
raw.method.should eq "{{ ivar.id }}"
raw.route.should eq "/users"
end
{% end %}

it "throws an exception with undefined method" do
expect_raises Swagger::UndefinedMethod do
Swagger::Action.new("fake", "/users")
Swagger::Action.new("fake", "/users", OK_RESPONSE)
end
end
end
7 changes: 4 additions & 3 deletions spec/swagger/controller_spec.cr
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
require "../spec_helper"
require "./action_helper"
require "../../src/swagger/controller"

describe Swagger::Controller do
describe "#new" do
@@ -12,11 +13,11 @@ describe Swagger::Controller do

it "should works with actions" do
raw = Swagger::Controller.new("Users", "User APIs", [
Swagger::Action.new("get", "/users", "List Users")
Swagger::Action.new("get", "/users", OK_RESPONSE, "List Users"),
])
raw.name.should eq "Users"
raw.description.should eq "User APIs"
raw.actions.should eq([Swagger::Action.new("get", "/users", "List Users")])
raw.actions.should eq([Swagger::Action.new("get", "/users", OK_RESPONSE, "List Users")])
raw.external_docs.should be_nil
end
end
2 changes: 1 addition & 1 deletion spec/swagger/objects/components_spec.cr
Original file line number Diff line number Diff line change
@@ -22,7 +22,7 @@ describe Swagger::Objects::Components do
raw.to_json.should eq %Q{{}}

raw = Swagger::Objects::Components.new(schemas: {
"user" => Swagger::Objects::Schema.use_reference("UserInfo")
"user" => Swagger::Objects::Schema.use_reference("UserInfo"),
})
raw.to_json.should eq %Q{{"schemas":{"user":{"$ref":"#/components/schemas/UserInfo"}}}}
end
15 changes: 8 additions & 7 deletions spec/swagger/objects/operation_spec.cr
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
require "../../spec_helper"
require "./response_helper"
require "../../../src/swagger/objects/operation"

describe Swagger::Objects::Operation do
describe ".from" do
@@ -7,13 +8,13 @@ describe Swagger::Objects::Operation do

describe "#new" do
it "should works" do
raw = Swagger::Objects::Operation.new
raw = Swagger::Objects::Operation.new SWAGGER_OK_RESPONSE
raw.responses.should eq SWAGGER_OK_RESPONSE
raw.summary.should be_nil
raw.description.should be_nil
raw.tags.should be_nil
raw.parameters.should be_nil
raw.request_body.should be_nil
raw.responses.should be_nil
raw.deprecated.should be_false
raw.security.should be_nil

@@ -26,13 +27,13 @@ describe Swagger::Objects::Operation do

describe "#to_json" do
it "should return default hash string" do
raw = Swagger::Objects::Operation.new
raw.to_json.should eq %Q{{"deprecated":false}}
raw = Swagger::Objects::Operation.new SWAGGER_OK_RESPONSE
raw.to_json.should eq %Q{{"responses":{"200":{"description":"OK"}},"deprecated":false}}
end

it "should returns OpenAPI spec Link json string" do
raw = Swagger::Objects::Operation.new(request_body: Swagger::Objects::RequestBody.new)
raw.to_json.should eq %Q{{"requestBody":{"required":false},"deprecated":false}}
raw = Swagger::Objects::Operation.new(SWAGGER_OK_RESPONSE, request_body: Swagger::Objects::RequestBody.new)
raw.to_json.should eq %Q{{"requestBody":{"required":false},"responses":{"200":{"description":"OK"}},"deprecated":false}}
end
end
end
6 changes: 3 additions & 3 deletions spec/swagger/objects/parameter_spec.cr
Original file line number Diff line number Diff line change
@@ -3,9 +3,9 @@ require "../../spec_helper"
describe Swagger::Objects::Parameter do
describe "#new" do
it "should works" do
raw = Swagger::Objects::Parameter.new("user_id", "query", Swagger::Objects::Schema.use_reference("User"))
raw = Swagger::Objects::Parameter.new("user_id", :Query, Swagger::Objects::Schema.use_reference("User"))
raw.name.should eq "user_id"
raw.parameter_location.should eq "query"
raw.parameter_location.should eq Swagger::Objects::Parameter::Location::Query
raw.schema.should eq Swagger::Objects::Schema.use_reference("User")
raw.description.should be_nil
raw.required.should be_false
@@ -17,7 +17,7 @@ describe Swagger::Objects::Parameter do

describe "#to_json" do
it "should return default hash string" do
raw = Swagger::Objects::Parameter.new("user_id", "query", Swagger::Objects::Schema.use_reference("User"))
raw = Swagger::Objects::Parameter.new("user_id", :Query, Swagger::Objects::Schema.use_reference("User"))
raw.to_json.should eq %Q{{"name":"user_id","schema":{"$ref":"#/components/schemas/User"},"in":"query","required":false,"allowEmptyValue":false,"deprecated":false}}
end
end
Loading

0 comments on commit cce09eb

Please sign in to comment.