Skip to content

Commit

Permalink
Added gradle to build the project.
Browse files Browse the repository at this point in the history
Updated Swagger2Markup dependency from 0.9.0 to 0.9.1 and added support to group paths by tags and order definitions
  • Loading branch information
Robert Winkler committed Nov 12, 2015
1 parent bb29d7b commit 1da607e
Show file tree
Hide file tree
Showing 7 changed files with 233 additions and 39 deletions.
45 changes: 7 additions & 38 deletions README.adoc
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
= Swagger2Markup Maven Plugin
:author: RedOwl Analytics
:version: 0.9.0
:version: 0.9.1
:hardbreaks:

image:https://travis-ci.org/Swagger2Markup/swagger2markup-maven-plugin.svg["Build Status", link="https://travis-ci.org/Swagger2Markup/swagger2markup-maven-plugin"] image:https://coveralls.io/repos/redowl/swagger2markup-maven-plugin/badge.svg["Coverage Status", link="https://coveralls.io/r/redowl/swagger2markup-maven-plugin"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"] image:https://img.shields.io/badge/Twitter-redowlytics-blue.svg["Twitter", link="https://twitter.com/redowlytics"]

== Overview

_NOTE: This is a nearly identical version of https://github.com/RobWin/swagger2markup-gradle-plugin[RobWin's swagger2Markup-gradle-plugin], except it's been ported over to maven. For a real commit history and all credit, see his project._
The primary goal of https://github.com/Swagger2Markup/swagger2markup[Swagger2Markup] is to *simplify the generation of an up-to-date RESTful API documentation by combining documentation that's been hand-written with auto-generated API documentation* produced by https://github.com/swagger-api[Swagger]. The result is intended to be an *up-to-date, easy-to-read, on- and offline user guide*, comparable to https://developer.github.com/v3/[GitHub's API documentation]. The output of the plugin can be used as an alternative to https://github.com/swagger-api/swagger-ui[swagger-ui] and can be served as static content.

The primary goal of https://github.com/RobWin/swagger2markup[Swagger2Markup] is to *simplify the generation of an up-to-date RESTful API documentation by combining documentation that's been hand-written with auto-generated API documentation* produced by https://github.com/swagger-api[Swagger]. The result is intended to be an *up-to-date, easy-to-read, on- and offline user guide*, comparable to https://developer.github.com/v3/[GitHub's API documentation]. The output of the plugin can be used as an alternative to https://github.com/swagger-api/swagger-ui[swagger-ui] and can be served as static content.

The Swagger2Markup Maven Plugin simplifies the usage of https://github.com/RobWin/swagger2markup[Swagger2Markup]. The Plugin adds a Maven goal which converts a Swagger JSON or YAML file into several *AsciiDoc* or *GitHub Flavored Markdown* documents. The plugin supports the Swagger 1.2 and 2.0 specification. Internally the plugin uses https://github.com/RobWin/swagger2markup[Swagger2Markup] which in turn uses the _official_ https://github.com/swagger-api/swagger-parser[swagger-parser] and RobWin's https://github.com/RobWin/markup-document-builder[markup-document-builder].
The Swagger2Markup Maven Plugin simplifies the usage of https://github.com/Swagger2Markup/swagger2markup[Swagger2Markup]. The Plugin adds a Maven goal which converts a Swagger JSON or YAML file into several *AsciiDoc* or *GitHub Flavored Markdown* documents. The plugin supports the Swagger 1.2 and 2.0 specification. Internally the plugin uses https://github.com/Swagger2Markup/swagger2markup[Swagger2Markup] which in turn uses the _official_ https://github.com/swagger-api/swagger-parser[swagger-parser] and a https://github.com/Swagger2Markup/markup-document-builder[markup-document-builder].

You can use the plugin to convert your contract-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the code-first approach and use Swagger2Markup together with https://github.com/swagger-api/swagger-core/tree/master/samples/java-jersey2[Swagger JAX-RS], https://github.com/springfox/springfox[springfox] or https://github.com/spring-projects/spring-restdocs[spring-restdocs]. See https://github.com/RobWin/swagger2markup#using-swagger2markup[Swagger2Markup user guide] for more details.

Expand All @@ -21,6 +19,10 @@ You can generate your HTML5, PDF and EPUB documentation via the https://github.c

The project requires at least JDK 7.

== Reference documentation

The documentation can be found at https://swagger2markup.readme.io[Reference documentation]

== Usage

_COMING SOON_: The project will be published in Maven Central.
Expand Down Expand Up @@ -250,39 +252,6 @@ public class Swagger2MarkupTest {
}
----

== Screenshots
=== Swagger source
image::images/swagger_json.PNG[swagger_json]

=== Generated AsciiDoc
image::images/asciidoc.PNG[asciidoc]

=== Generated Markdown
image::images/markdown.PNG[markdown]

=== Generated HTML using AsciidoctorJ
image::images/asciidoc_html.PNG[asciidoc_html]

=== Generated PDF using AsciidoctorJ
image::images/asciidoc_pdf.PNG[asciidoc_pdf]

== Release Notes

=== Version 0.1.0
* Initial Version
* Ported over https://github.com/RobWin/swagger2markup-gradle-plugin[RobWin's swagger2Markup-gradle-plugin] to maven plugin

=== Version 0.6.3
* Updated Swagger2Markup dependency to 0.6.3
* Exposed Swagger2Markup's new "separateDefinitions" in plugin configuration
* Improved Testing coverage

=== Version 0.7.0
* Updated Swagger2Markup dependency to 0.7.0

=== Version 0.7.1
* Updated Swagger2Markup dependency to 0.7.1

== License

Copyright 2015 RedOwl Analytics
Expand Down
22 changes: 22 additions & 0 deletions RELEASENOTES.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
= Release Notes

=== Version 0.1.0
* Initial Version
* Ported over https://github.com/RobWin/swagger2markup-gradle-plugin[RobWin's swagger2Markup-gradle-plugin] to maven plugin

=== Version 0.6.3
* Updated Swagger2Markup dependency to 0.6.3
* Exposed Swagger2Markup's new "separateDefinitions" in plugin configuration
* Improved Testing coverage

=== Version 0.7.0
* Updated Swagger2Markup dependency to 0.7.0

=== Version 0.7.1
* Updated Swagger2Markup dependency to 0.7.1

== Version 0.9.0
* Updated Swagger2Markup dependency from 0.8.0 to 0.9.0

=== Version 0.9.1
* Updated Swagger2Markup dependency from 0.9.0 to 0.9.1
81 changes: 81 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
buildscript {
repositories {
jcenter()
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath 'org.kt3k.gradle.plugin:coveralls-gradle-plugin:2.0.1'
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.2'
//classpath "com.gradle.publish:plugin-publish-plugin:0.9.0"
}
}

group = 'io.github.robwin'
version = '0.9.1'
description = 'A Swagger to Markup (AsciiDoc and Markdown) converter Maven Plugin.'

apply plugin: 'groovy'
apply plugin: 'maven-publish'
apply plugin: 'jacoco'
apply plugin: 'com.github.kt3k.coveralls'
apply plugin: 'com.jfrog.bintray'
apply from: 'gradle/publishing.gradle'
//apply plugin: 'java-gradle-plugin'
//apply plugin: "com.gradle.plugin-publish"

tasks.withType(GroovyCompile) {
sourceCompatibility = "1.7"
targetCompatibility = "1.7"
options.deprecation = true
options.encoding = 'UTF-8'
options.compilerArgs << "-Xlint:unchecked"
}

repositories {
jcenter()
mavenCentral()
mavenLocal()
}

dependencies {
compile 'io.github.robwin:swagger2markup:0.9.1'
compile 'org.apache.maven:maven-plugin-api:3.3.3'
compile 'org.apache.maven.plugin-tools:maven-plugin-annotations:3.4'
testCompile 'junit:junit:4.12'
testCompile 'ch.qos.logback:logback-classic:1.1.3'
testCompile 'org.assertj:assertj-core:2.1.0'
testCompile 'org.mockito:mockito-core:1.10.19'
}


task sourcesJar(type: Jar, dependsOn: classes) {
classifier = 'sources'
from sourceSets.main.allSource
}

task javadocJar(type: Jar, dependsOn: javadoc) {
classifier = 'javadoc'
from javadoc.destinationDir
}

jacocoTestReport {
reports {
xml.enabled = true // coveralls plugin depends on xml format report
html.enabled = true
}
}

tasks.coveralls {
dependsOn 'check'
}

artifacts {
archives sourcesJar
archives javadocJar
}

task wrapper(type: Wrapper) {
gradleVersion = '2.8'
}
100 changes: 100 additions & 0 deletions gradle/publishing.gradle
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
import java.text.SimpleDateFormat

Date buildTimeAndDate = new Date()
ext {
buildDate = new SimpleDateFormat('yyyy-MM-dd').format(buildTimeAndDate)
buildTime = new SimpleDateFormat('HH:mm:ss.SSSZ').format(buildTimeAndDate)
}

def projectArtifactId = 'swagger2markup-gradle-plugin'

jar {
manifest {
attributes(
'Built-By': 'Robert Winkler',
'Created-By': System.properties['java.version'] + " (" + System.properties['java.vendor'] + " " + System.properties['java.vm.version'] + ")",
'Build-Date': project.buildDate,
'Build-Time': project.buildTime,
'Specification-Title': projectArtifactId,
'Specification-Version': project.version,
'Implementation-Title': projectArtifactId,
'Implementation-Version': project.version
)
}
}

if (!project.hasProperty('bintrayUsername')) ext.bintrayUsername = ''
if (!project.hasProperty('bintrayApiKey')) ext.bintrayApiKey = ''
if (!project.hasProperty('gpgPassphrase')) ext.gpgPassphrase = ''
if (!project.hasProperty('ossUser')) ext.ossUser = ''
if (!project.hasProperty('ossPassword')) ext.ossPassword = ''

bintray {
user = project.bintrayUsername
key = project.bintrayApiKey
dryRun = false //Whether to run this as dry-run, without deploying
publish = true //If version should be auto published after an upload
publications = ['mavenJava']
pkg {
repo = 'maven'
name = 'swagger2markup-maven-plugin'
websiteUrl = 'https://github.com/Swagger2Markup/swagger2markup-maven-plugin'
issueTrackerUrl = 'https://github.com/Swagger2Markup/swagger2markup-maven-plugin/issues'
vcsUrl = 'https://github.com/Swagger2Markup/swagger2markup-maven-plugin.git'
desc = 'A Swagger to Markup (AsciiDoc and Markdown) converter maven Plugin.'
licenses = ['Apache-2.0']
version {
vcsTag = project.version
gpg {
sign = true //Determines whether to GPG sign the files. The default is false
passphrase = project.gpgPassphrase //Optional. The passphrase for GPG signing'
}
mavenCentralSync {
sync = true //Optional (true by default). Determines whether to sync the version to Maven Central.
user = ossUser //OSS user token
password = ossPassword //OSS user password
}
}
}
}

publishing {
publications {
mavenJava(MavenPublication) {
from components.java
pom.withXml {
def devs = ['RobWin': 'Robert Winkler']
def root = asNode()

root.dependencies.'*'.findAll() {
it.scope.text() == 'runtime' && project.configurations.compile.allDependencies.find { dep ->
dep.name == it.artifactId.text()
}
}.each() {
it.scope*.value = 'compile'
}

root.appendNode('name', 'swagger2markup-gradle-plugin')
root.appendNode('packaging', 'jar')
root.appendNode('url', 'https://github.com/Swagger2Markup/swagger2markup-gradle-plugin')
root.appendNode('description', 'A Swagger to Markup (AsciiDoc and Markdown) converter Gradle Plugin.')

def license = root.appendNode('licenses').appendNode('license')
license.appendNode('name', 'Apache-2.0')
license.appendNode('url', 'https://github.com/Swagger2Markup/swagger2markup-gradle-plugin/blob/master/LICENSE.txt')
license.appendNode('distribution', 'repo')

root.appendNode('scm').appendNode('url', 'https://github.com/Swagger2Markup/swagger2markup-gradle-plugin.git')

def developers = root.appendNode('developers')
devs.each {
def d = developers.appendNode('developer')
d.appendNode('id', it.key)
d.appendNode('name', it.value)
}
}
artifact sourcesJar
artifact javadocJar
}
}
}
6 changes: 6 additions & 0 deletions gradle/wrapper/gradle-wrapper.properties
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#Thu Nov 12 14:48:47 CET 2015
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-2.8-bin.zip
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

<groupId>com.redowlanalytics</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>0.9.0</version>
<version>0.9.1</version>
<packaging>maven-plugin</packaging>

<name>Swagger2Markup Maven Plugin</name>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
package com.redowlanalytics.swagger2markup;

import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.GroupBy;
import io.github.robwin.swagger2markup.OrderBy;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;

import org.apache.maven.plugin.AbstractMojo;
Expand Down Expand Up @@ -30,6 +32,12 @@ public class Swagger2MarkupMojo extends AbstractMojo {
@Parameter(property = PREFIX + "markupLanguage", defaultValue = "asciidoc", required = true)
protected String markupLanguage = "asciidoc";

@Parameter(property = PREFIX + "pathsGroupedBy", required = false)
protected String pathsGroupedBy;

@Parameter(property = PREFIX + "definitionsOrderedBy", required = false)
protected String definitionsOrderedBy;

@Parameter(property = PREFIX + "examplesDirectory", required = false)
protected File examplesDirectory;

Expand All @@ -51,6 +59,8 @@ public void execute() throws MojoExecutionException, MojoFailureException {
getLog().debug("convertSwagger2markup task started");
getLog().debug("InputDir: " + inputDirectory);
getLog().debug("OutputDir: " + outputDirectory);
getLog().debug("PathsGroupedBy: " + pathsGroupedBy);
getLog().debug("DefinitionsOrderedBy: " + definitionsOrderedBy);
getLog().debug("ExamplesDir: " + examplesDirectory);
getLog().debug("DescriptionsDir: " + descriptionsDirectory);
getLog().debug("SchemasDir: " + schemasDirectory);
Expand All @@ -75,6 +85,12 @@ public void execute() throws MojoExecutionException, MojoFailureException {
final Swagger2MarkupConverter.Builder builder = Swagger2MarkupConverter
.from(file.getAbsolutePath())
.withMarkupLanguage(markupLanguageEnum);
if(pathsGroupedBy != null){
builder.withPathsGroupedBy(GroupBy.valueOf(pathsGroupedBy.toUpperCase()));
}
if(definitionsOrderedBy != null){
builder.withDefinitionsOrderedBy(OrderBy.valueOf(definitionsOrderedBy.toUpperCase()));
}
if(examplesDirectory != null){
getLog().debug("Include examples is enabled.");
builder.withExamples(examplesDirectory.getAbsolutePath());
Expand Down

0 comments on commit 1da607e

Please sign in to comment.