soil is schema language for REST and JSON api and swift / kotlin client code generator.
Other tools are more good if you want:
Your REST resource is called Entity
and defined by entity
keyword in soil.
For example, User
resource on your REST api can is defined with .soil file.
entity User {
field id: Integer
mutable field name: String
}
entity
: start of Entity.User
: entity name.field id: Integer
: User
entity has id
Integer property.mutable field name: String
: User
entity has name
mutable String property.Single .soil file can contain multiple entity
directives.
Entity has mapped any endpoints on REST api.
Each entity
directives can contain any endpoint
directives.
entity User {
...
endpoint GET /users {
success {
field users: List<User>
}
}
}
endpoint GET /users
: Endpoint. This endpoint accessed by GET method and /users
path.success
directive: successful response (status code 2xx) schema. like entity
directive.In the REST api, most of the time there are two types of resource fields: writable and read-only. In the POST and PUT methods, only the values of writable fields should be sent. soil handles this difference by separating "read-time Entity" and "write-time Entity".
entity User {
field id: Integer
mutable field name: String
}
If entity has mutable
or writer
field, entity has write-time mode.
For example, this User
entity exports as Swift code.
public final class User: Decodable {
public let id: Int
public var name: String
public struct Writer: Encodable {
public let name: String
/// - Parameters:
/// - name: {no comment}
public init(name: String) {
self.name = name
}
}
}
User
is read-time entity, User.Writer
is write-time entity.
Each recipe presents a specific sample of soil schema detailed features.
soil is written by nodejs and managed by npm.
$ npm install -g soil-schema
soil scneario runner helps you test REST api.
$ npx soil replay
scenario Test Scenario {
GET /sample
}
soil http request to GET /sample
endpoint.
scenario Comment {
GET /articles/search {
query = Search Query Parameter
}
POST /comments {
body = Comment body
}
}
Use id
directive in endpoint block, endpoint is identified by id string.
You use endpoint reference that join by dot notation entity name and endpoint id in scenario block.
entity User {
field id: Int
mutable field name: String
POST /users {
id register
request {
field user: User
}
success {
field user: User
}
}
}
scenario Register User {
User.register { # Actually it uses `POST /users` endpoint.
name = User Name
}
}
api
configsoil can be configured for your REST Api in the api
section of soil.config.js
.
key | description | default |
---|---|---|
api.base | Base URL for scenario runner. e.g. https://api.example.com/v1 . Required for replay sub-command. |
undefined |
api.booleanQuery | Boolean type parsing and stringify strategy. |
'set-only-true' |
api.headers | Custom headers collection used by scenario runner. | {} |
You run soil generate command in your cli with target name, export code.
$ npx soil generate -g [target]
Supported targets are:
swift
)kotlin
)soil supports Swift code generation. Generated code has no dependencies, use your api request / response client class.
$ npx soil generate -g swift
Instead of writing your own code, you can use soil-swift.
module.exports = {
swift: {
use: ['soil-swift'],
},
}
soil supports Kotlin code generation.
$ npx soil generate -g kotlin