Skip to content

acme-software/typeswagger

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

TypeSwagger - A Swagger / OpenApi Spec DSL for Scala

License: MIT Build Status Codacy Badge

TypeSwagger provides a typesafe Scala DSL to build OpenApi (Swagger) Specifications. It can be used within any Scala project to generate HTTP API documentations.

Example

The following example defines a simple api with two endpoints (GET and DELETE) on one path (/user/{id}). The example contains mandatory information, and also some, but not all optional fields. For better readability, optional fields are calld by value.

import ch.acmesoftware.typeswagger.v3.OpenApi
import ch.acmesoftware.typeswagger.v3.OpenApi._
import ch.acmesoftware.typeswagger.v3.Implicits._

OpenApi.create("ApiDoc", "1.0.0").
  // add global information
  withInfo(license = "MIT", licenseUrl = "https://opensource.org/licenses/MIT").
  // add a tag
  withTag("testtag", "A tag description", externalDocs = doc("http://link.to.doc")).
  // define an api path
  path("/user/{id}", summary = "Path summary") {
    // http GET operation  on the path
    (GET >> op("A summary", "GET operation for this route").
      withParameter("id", PATH, Schema.int, description = "The id...", required = true).
      withParameter("comment", QUERY, Schema.string, description = "Some deprecated comment", 
                    deprecated = true).
      withTag("testtag")) ~
    // http DELETE operation on the path
    (DELETE >> op("Delete operation").
      withParameter("id", PATH, Schema.int, description = "The id...", required = true))
  }.
  // add endpoint server(s)
  withServer("http://localhost:9000/api").
  withServer("https://production.tld/api", Some("Production Server")).
  // build json string
  toJson()

Usage

Install the Ivy depenency via SBT:

"ch.acmesoftware" %% "typeswagger" % "{version}"

Add imports:

import ch.acmesoftware.typeswagger.v3.OpenApi
import ch.acmesoftware.typeswagger.v3.OpenApi._

// syntactic sugar for convenient DSL, but optional
import ch.acmesoftware.typeswagger.v3.Implicits._ 

Info

Add global information using the withInfo function. All parameters are optional. If not using the implicits, use Some("str") as parameter value:

import ch.acmesoftware.typeswagger.v3.OpenApi
import ch.acmesoftware.typeswagger.v3.OpenApi._
import ch.acmesoftware.typeswagger.v3.Implicits._

OpenApi.create("ApiDoc", "1.0.0", description = "API Doc built with TypeSwagger", termsOfService = "/tos").
  withInfo(license = "MIT", licenseUrl = "https://opensource.org/licenses/MIT", 
           contactName = "John Doe", contactEmail = "info@server.tld", contactUrl = "https://webpage.tld")

Features

  • Convenient, typesafe DSL to define OpenApi v3 specifications
  • Integrated JSON rendering
  • Integrated YAML rendering (TODO)
  • Java API (TODO)
  • Integration with common HTTP-Frameworks (TODO)

Contributions

Please use the GitHub issue tracking and PullRequests. Any help is very welcome.

License

This project is licensed under the MIT license. See LICENSE for more information.

About

A Swagger / OpenApi Specification DSL for Scala

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages