mindol1004/swagger2markup
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fixed issue: ResponseModel from api declaration is not rendered

Browse Source 
Fixed issue: @ApiModelProperty metadata are ignored for definitions file
Fixed issue: logback.xml on the classpath
This commit is contained in:
Robert Winkler
2015-04-15 16:30:37 +02:00
parent 04d1773c03
commit ec610f4fbb
14 changed files with 368 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java
View File

@@ -45,10 +45,21 @@ public class Swagger2MarkupConverter {
* @return a Swagger2MarkupConverter
*/
public static Builder from(String swaggerSource){
Validate.notEmpty(swaggerSource, "swaggerSource must not be null!");
Validate.notEmpty(swaggerSource, "swaggerSource must not be empty!");
return new Builder(swaggerSource);
}
/**
* Creates a Swagger2MarkupConverter.Builder from a given Swagger model.
*
* @param swagger the Swagger source.
* @return a Swagger2MarkupConverter
*/
public static Builder from(Swagger swagger){
Validate.notNull(swagger, "swagger must not be null!");
return new Builder(swagger);
}
/**
* Builds the document with the given markup language and stores
* the files in the given folder.
@@ -61,6 +72,15 @@ public class Swagger2MarkupConverter {
buildDocuments(targetFolderPath);
}
/**
* Builds the document with the given markup language and returns it as a String
*
* @return a the document as a String
*/
public String asString() throws IOException{
return buildDocuments();
}
/**
* Writes a file for the Paths (API) and a file for the Definitions (Model)
@@ -72,6 +92,16 @@ public class Swagger2MarkupConverter {
new DefinitionsDocument(swagger, markupLanguage, schemasFolderPath).build().writeToFile(directory, DEFINITIONS_DOCUMENT, StandardCharsets.UTF_8);
}
/**
* Returns a file for the Paths (API) and a file for the Definitions (Model)
* @return a the document as a String
*/
private String buildDocuments() throws IOException {
return new PathsDocument(swagger, markupLanguage, examplesFolderPath).build().toString()
.concat(new DefinitionsDocument(swagger, markupLanguage, schemasFolderPath).build().toString());
}
public static class Builder{
private final Swagger swagger;
@@ -88,6 +118,17 @@ public class Swagger2MarkupConverter {
swagger = new SwaggerParser().read(swaggerSource);
}
/**
* Creates a Builder using a given Swagger model.
*
* @param swagger the Swagger source.
*/
Builder(Swagger swagger){
this.swagger = swagger;
}
public Swagger2MarkupConverter build(){
return new Swagger2MarkupConverter(markupLanguage, swagger, examplesFolderPath, schemasFolderPath);
}

21
src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java
View File

@@ -2,8 +2,10 @@ package io.github.robwin.swagger2markup.builder.document;
import com.wordnik.swagger.models.Model;
import com.wordnik.swagger.models.Swagger;
import com.wordnik.swagger.models.properties.AbstractProperty;
import com.wordnik.swagger.models.properties.Property;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.utils.PropertyUtils;
import org.apache.commons.collections.MapUtils;
import org.apache.commons.io.FileUtils;
import org.apache.commons.lang.StringUtils;
@@ -26,8 +28,6 @@ public class DefinitionsDocument extends MarkupDocument {
private static final List<String> IGNORED_DEFINITIONS = Arrays.asList("Void");
private static final String JSON_SCHEMA = "JSON Schema";
private static final String XML_SCHEMA = "XML Schema";
private static final String NAME_COLUMN = "Name";
private static final String TYPE_COLUMN = "Type";
public static final String JSON_SCHEMA_EXTENSION = ".json";
public static final String XML_SCHEMA_EXTENSION = ".xsd";
public static final String JSON = "json";
@@ -104,13 +104,22 @@ public class DefinitionsDocument extends MarkupDocument {
private void definition(String definitionName, Model model) {
this.markupDocBuilder.sectionTitleLevel2(definitionName);
Map<String, Property> properties = model.getProperties();
List<String> csvContent = new ArrayList<>();
csvContent.add(NAME_COLUMN + DELIMITER + TYPE_COLUMN + DELIMITER + REQUIRED_COLUMN);
List<String> headerAndContent = new ArrayList<>();
List<String> header = Arrays.asList(NAME_COLUMN, DESCRIPTION_COLUMN, SCHEMA_COLUMN, REQUIRED_COLUMN);
headerAndContent.add(StringUtils.join(header, DELIMITER));
for (Map.Entry<String, Property> propertyEntry : properties.entrySet()) {
Property property = propertyEntry.getValue();
csvContent.add(propertyEntry.getKey() + DELIMITER + property.getType() + DELIMITER + property.getRequired());
String description = "";
if(property instanceof AbstractProperty){
if(StringUtils.isNotBlank(property.getDescription())){
description = property.getDescription();
}
}
String type = PropertyUtils.getType(property, markupLanguage);
List<String> content = Arrays.asList(propertyEntry.getKey(), description, type, Boolean.toString(property.getRequired()));
headerAndContent.add(StringUtils.join(content, DELIMITER));
}
this.markupDocBuilder.tableWithHeaderRow(csvContent);
this.markupDocBuilder.tableWithHeaderRow(headerAndContent);
}
private void definitionSchema(String definitionName) throws IOException {

6
src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java
View File

@@ -15,8 +15,12 @@ import java.nio.charset.Charset;
*/
public abstract class MarkupDocument {
protected static final String DELIMITER = ",";
protected static final String DELIMITER = "|";
protected static final String REQUIRED_COLUMN = "Required";
protected static final String SCHEMA_COLUMN = "Schema";
protected static final String NAME_COLUMN = "Name";
protected static final String DESCRIPTION_COLUMN = "Description";
protected static final String DESCRIPTION = DESCRIPTION_COLUMN;
protected Logger logger = LoggerFactory.getLogger(getClass());
protected Swagger swagger;
protected MarkupLanguage markupLanguage;

145
src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java
View File

@@ -2,17 +2,22 @@ package io.github.robwin.swagger2markup.builder.document;
import com.wordnik.swagger.models.*;
import com.wordnik.swagger.models.parameters.Parameter;
import com.wordnik.swagger.models.properties.Property;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.utils.ParameterUtils;
import io.github.robwin.swagger2markup.utils.PropertyUtils;
import org.apache.commons.collections.CollectionUtils;
import org.apache.commons.collections.MapUtils;
import org.apache.commons.io.FileUtils;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.WordUtils;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
@@ -21,20 +26,27 @@ import java.util.Map;
*/
public class PathsDocument extends MarkupDocument {
private static final String PATHS = "Paths";
private static final String VERSION = "Version: ";
private static final String DESCRIPTION_COLUMN = "Description";
private static final String DESCRIPTION = DESCRIPTION_COLUMN;
private static final String CONTACT_NAME = "Contact: ";
private static final String CONTACT_EMAIL = "Contact Email: ";
private static final String LICENSE = "License: ";
private static final String LICENSE_URL = "License URL: ";
private static final String TERMS_OF_SERVICE = "Terms of service: ";
private static final String HOST = "Host: ";
private static final String BASE_PATH = "BasePath: ";
private static final String SCHEMES = "Schemes: ";
private static final String PARAMETERS = "Parameters";
private static final String PRODUCES = "Produces";
private static final String CONSUMES = "Consumes";
private static final String TAGS = "Tags";
private static final String RESPONSES = "Responses";
private static final String EXAMPLE_REQUEST = "Example request";
private static final String EXAMPLE_RESPONSE = "Example response";
private static final String NAME_COLUMN = "Name";
private static final String LOCATED_IN_COLUMN = "Located in";
private static final String CODE_COLUMN = "Code";
public static final String REQUEST_EXAMPLE_FILE_NAME = "request";
public static final String RESPONSE_EXAMPLE_FILE_NAME = "response";
private static final String TYPE_COLUMN = "Type";
private static final String HTTP_CODE_COLUMN = "HTTP Code";
private static final String REQUEST_EXAMPLE_FILE_NAME = "request";
private static final String RESPONSE_EXAMPLE_FILE_NAME = "response";
private boolean examplesEnabled;
private String examplesFolderPath;
@@ -58,32 +70,69 @@ public class PathsDocument extends MarkupDocument {
@Override
public MarkupDocument build() throws IOException {
documentHeader(swagger.getInfo());
paths(swagger.getPaths());
documentHeader();
paths();
return this;
}
/**
* Builds the document header
*
* @param info the Swagger Info
* Builds the document header of the swagger model
*/
private void documentHeader(Info info) {
this.markupDocBuilder
.documentTitle(info.getTitle())
.textLine(info.getDescription())
.textLine(VERSION + info.getVersion())
.newLine();
private void documentHeader() {
Info info = swagger.getInfo();
this.markupDocBuilder.documentTitle(info.getTitle());
if(StringUtils.isNotBlank(info.getDescription())){
this.markupDocBuilder.textLine(info.getDescription());
}
if(StringUtils.isNotBlank(info.getVersion())){
this.markupDocBuilder.textLine(VERSION + info.getVersion());
}
Contact contact = info.getContact();
if(contact != null){
if(StringUtils.isNotBlank(contact.getName())){
this.markupDocBuilder.textLine(CONTACT_NAME + contact.getName());
}
if(StringUtils.isNotBlank(contact.getEmail())){
this.markupDocBuilder.textLine(CONTACT_EMAIL + contact.getEmail());
}
}
License license = info.getLicense();
if(license != null) {
if (StringUtils.isNotBlank(license.getName())) {
this.markupDocBuilder.textLine(LICENSE + license.getName());
}
if (StringUtils.isNotBlank(license.getUrl())) {
this.markupDocBuilder.textLine(LICENSE_URL + license.getUrl());
}
}
if(StringUtils.isNotBlank(info.getTermsOfService())){
this.markupDocBuilder.textLine(TERMS_OF_SERVICE + info.getTermsOfService());
}
this.markupDocBuilder.newLine();
if(StringUtils.isNotBlank(swagger.getHost())){
this.markupDocBuilder.textLine(HOST + swagger.getHost());
}
if(StringUtils.isNotBlank(swagger.getBasePath())){
this.markupDocBuilder.textLine(BASE_PATH + swagger.getBasePath());
}
if(CollectionUtils.isNotEmpty(swagger.getSchemes())){
List<String> schemes = new ArrayList<>();
for(Scheme scheme : swagger.getSchemes()){
schemes.add(scheme.toString());
}
this.markupDocBuilder.textLine(SCHEMES + StringUtils.join(schemes, ", "));
}
this.markupDocBuilder.newLine();
}
/**
* Builds all paths of the Swagger file
*
* @param paths a Map of Swagger Paths
* Builds all paths of the Swagger model
*/
private void paths(Map<String, Path> paths) throws IOException {
private void paths() throws IOException {
Map<String, Path> paths = swagger.getPaths();
if(MapUtils.isNotEmpty(paths)) {
//this.documentBuilder.sectionTitleLevel1(FEATURES);
this.markupDocBuilder.sectionTitleLevel1(PATHS);
for (Map.Entry<String, Path> entry : paths.entrySet()) {
Path path = entry.getValue();
path("GET", entry.getKey(), path.getGet());
@@ -110,21 +159,21 @@ public class PathsDocument extends MarkupDocument {
responsesSection(operation);
consumesSection(operation);
producesSection(operation);
tagsSection(operation);
examplesSection(operation);
}
}
private void pathTitle(String httpMethod, String resourcePath, Operation operation) {
String summary = operation.getSummary();
String title;
if(StringUtils.isNotBlank(summary)) {
title = summary;
this.markupDocBuilder.sectionTitleLevel1(title);
this.markupDocBuilder.sectionTitleLevel2(title);
this.markupDocBuilder.listing(httpMethod + " " + resourcePath);
}else{
title = httpMethod + " " + resourcePath;
this.markupDocBuilder.sectionTitleLevel1(title);
this.markupDocBuilder.sectionTitleLevel2(title);
}
if (logger.isInfoEnabled()) {
logger.info("Path processed: {}", title);
@@ -134,7 +183,7 @@ public class PathsDocument extends MarkupDocument {
private void descriptionSection(Operation operation) {
String description = operation.getDescription();
if(StringUtils.isNotBlank(description)){
this.markupDocBuilder.sectionTitleLevel2(DESCRIPTION);
this.markupDocBuilder.sectionTitleLevel3(DESCRIPTION);
this.markupDocBuilder.paragraph(description);
}
}
@@ -142,20 +191,26 @@ public class PathsDocument extends MarkupDocument {
private void parametersSection(Operation operation) {
List<Parameter> parameters = operation.getParameters();
if(CollectionUtils.isNotEmpty(parameters)){
List<String> csvContent = new ArrayList<>();
csvContent.add(NAME_COLUMN + DELIMITER + LOCATED_IN_COLUMN + DELIMITER + DESCRIPTION_COLUMN + DELIMITER + REQUIRED_COLUMN);
List<String> headerAndContent = new ArrayList<>();
// Table header row
List<String> header = Arrays.asList(TYPE_COLUMN, NAME_COLUMN, DESCRIPTION_COLUMN, REQUIRED_COLUMN, SCHEMA_COLUMN);
headerAndContent.add(StringUtils.join(header, DELIMITER));
for(Parameter parameter : parameters){
csvContent.add(parameter.getName() + DELIMITER + parameter.getIn() + DELIMITER + parameter.getDescription() + DELIMITER + parameter.getRequired());
String type = ParameterUtils.getType(parameter, markupLanguage);
String parameterType = WordUtils.capitalize(parameter.getIn() + "Parameter");
// Table content row
List<String> content = Arrays.asList(parameterType, parameter.getName(), parameter.getDescription(), Boolean.toString(parameter.getRequired()), type);
headerAndContent.add(StringUtils.join(content, DELIMITER));
}
this.markupDocBuilder.sectionTitleLevel2(PARAMETERS);
this.markupDocBuilder.tableWithHeaderRow(csvContent);
this.markupDocBuilder.sectionTitleLevel3(PARAMETERS);
this.markupDocBuilder.tableWithHeaderRow(headerAndContent);
}
}
private void consumesSection(Operation operation) {
List<String> consumes = operation.getConsumes();
if(CollectionUtils.isNotEmpty(consumes)){
this.markupDocBuilder.sectionTitleLevel2(CONSUMES);
this.markupDocBuilder.sectionTitleLevel3(CONSUMES);
this.markupDocBuilder.unorderedList(consumes);
}
@@ -164,11 +219,19 @@ public class PathsDocument extends MarkupDocument {
private void producesSection(Operation operation) {
List<String> produces = operation.getProduces();
if(CollectionUtils.isNotEmpty(produces)){
this.markupDocBuilder.sectionTitleLevel2(PRODUCES);
this.markupDocBuilder.sectionTitleLevel3(PRODUCES);
this.markupDocBuilder.unorderedList(produces);
}
}
private void tagsSection(Operation operation) {
List<String> tags = operation.getTags();
if(CollectionUtils.isNotEmpty(tags)){
this.markupDocBuilder.sectionTitleLevel3(TAGS);
this.markupDocBuilder.unorderedList(tags);
}
}
/**
* Builds the example section of a Swagger Operation
*
@@ -198,7 +261,7 @@ public class PathsDocument extends MarkupDocument {
for (String fileNameExtension : markupLanguage.getFileNameExtensions()) {
java.nio.file.Path path = Paths.get(examplesFolderPath, exampleFolder, exampleFileName + fileNameExtension);
if (Files.isReadable(path)) {
this.markupDocBuilder.sectionTitleLevel2(title);
this.markupDocBuilder.sectionTitleLevel3(title);
this.markupDocBuilder.paragraph(FileUtils.readFileToString(path.toFile(), StandardCharsets.UTF_8).trim());
if (logger.isInfoEnabled()) {
logger.info("Example file processed: {}", path);
@@ -216,12 +279,18 @@ public class PathsDocument extends MarkupDocument {
Map<String, Response> responses = operation.getResponses();
if(MapUtils.isNotEmpty(responses)){
List<String> csvContent = new ArrayList<>();
csvContent.add(CODE_COLUMN + DELIMITER + DESCRIPTION_COLUMN);
csvContent.add(HTTP_CODE_COLUMN + DELIMITER + DESCRIPTION_COLUMN + DELIMITER + SCHEMA_COLUMN);
for(Map.Entry<String, Response> entry : responses.entrySet()){
Response response = entry.getValue();
csvContent.add(entry.getKey() + DELIMITER + response.getDescription());
if(response.getSchema() != null){
Property property = response.getSchema();
String type = PropertyUtils.getType(property, markupLanguage);
csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + type);
}else{
csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + "No Content");
}
}
this.markupDocBuilder.sectionTitleLevel2(RESPONSES);
this.markupDocBuilder.sectionTitleLevel3(RESPONSES);
this.markupDocBuilder.tableWithHeaderRow(csvContent);
}
}

27
src/main/java/io/github/robwin/swagger2markup/utils/ModelUtils.java Normal file
View File

@@ -0,0 +1,27 @@
package io.github.robwin.swagger2markup.utils;
import com.wordnik.swagger.models.ArrayModel;
import com.wordnik.swagger.models.Model;
import com.wordnik.swagger.models.ModelImpl;
import com.wordnik.swagger.models.RefModel;
import io.github.robwin.markup.builder.MarkupLanguage;
import org.apache.commons.lang.Validate;
public final class ModelUtils {
public static String getType(Model model, MarkupLanguage markupLanguage) {
Validate.notNull(model, "model must not be null!");
if (model instanceof ModelImpl) {
return ((ModelImpl) model).getType();
} else if (model instanceof RefModel) {
switch (markupLanguage){
case ASCIIDOC: return "<<" + ((RefModel) model).getSimpleRef() + ">>";
default: return ((RefModel) model).getSimpleRef();
}
} else if (model instanceof ArrayModel) {
ArrayModel arrayModel = ((ArrayModel) model);
return PropertyUtils.getType(arrayModel.getItems(), markupLanguage) + " " + arrayModel.getType();
}
return "NOT FOUND";
}
}

62
src/main/java/io/github/robwin/swagger2markup/utils/ParameterUtils.java Normal file
View File

@@ -0,0 +1,62 @@
package io.github.robwin.swagger2markup.utils;
import com.wordnik.swagger.models.Model;
import com.wordnik.swagger.models.parameters.*;
import io.github.robwin.markup.builder.MarkupLanguage;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.Validate;
public final class ParameterUtils {
public static String getType(Parameter parameter, MarkupLanguage markupLanguage){
Validate.notNull(parameter, "property must not be null!");
String type = "NOT FOUND";
if(parameter instanceof BodyParameter){
BodyParameter bodyParameter = (BodyParameter)parameter;
Model model = bodyParameter.getSchema();
type = ModelUtils.getType(model, markupLanguage);
}
else if(parameter instanceof PathParameter){
PathParameter pathParameter = (PathParameter)parameter;
type = getTypeWithFormat(pathParameter.getType(), pathParameter.getFormat());
}
else if(parameter instanceof QueryParameter){
QueryParameter queryParameter = (QueryParameter)parameter;
type = getTypeWithFormat(queryParameter.getType(), queryParameter.getFormat());
if(type.equals("array")){
String collectionFormat = queryParameter.getCollectionFormat();
type = collectionFormat + " " + PropertyUtils.getType(queryParameter.getItems(), markupLanguage) + " " + type;
}
}
else if(parameter instanceof HeaderParameter){
HeaderParameter headerParameter = (HeaderParameter)parameter;
type = getTypeWithFormat(headerParameter.getType(), headerParameter.getFormat());
}
else if(parameter instanceof FormParameter){
FormParameter formParameter = (FormParameter)parameter;
type = formParameter.getType();
}
else if(parameter instanceof CookieParameter){
CookieParameter cookieParameter = (CookieParameter)parameter;
type = getTypeWithFormat(cookieParameter.getType(), cookieParameter.getFormat());
}
else if(parameter instanceof RefParameter){
RefParameter refParameter = (RefParameter)parameter;
switch (markupLanguage){
case ASCIIDOC: return "<<" + refParameter.getSimpleRef() + ">>";
default: return refParameter.getSimpleRef();
}
}
return type;
}
private static String getTypeWithFormat(String typeWithoutFormat, String format) {
String type;
if(StringUtils.isNotBlank(format)){
type = typeWithoutFormat + " (" + format + ")";
}else{
type = typeWithoutFormat;
}
return type;
}
}

47
src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java Normal file
View File

@@ -0,0 +1,47 @@
package io.github.robwin.swagger2markup.utils;
import com.wordnik.swagger.models.properties.ArrayProperty;
import com.wordnik.swagger.models.properties.Property;
import com.wordnik.swagger.models.properties.RefProperty;
import com.wordnik.swagger.models.properties.StringProperty;
import io.github.robwin.markup.builder.MarkupLanguage;
import org.apache.commons.collections.CollectionUtils;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.Validate;
import java.util.List;
public final class PropertyUtils {
public static String getType(Property property, MarkupLanguage markupLanguage){
Validate.notNull(property, "property must not be null!");
String type;
if(property instanceof RefProperty){
RefProperty refProperty = (RefProperty)property;
switch (markupLanguage){
case ASCIIDOC: return "<<" + refProperty.getSimpleRef() + ">>";
default: return refProperty.getSimpleRef();
}
}else if(property instanceof ArrayProperty){
ArrayProperty arrayProperty = (ArrayProperty)property;
Property items = arrayProperty.getItems();
type = getType(items, markupLanguage) + " " + arrayProperty.getType();
}else if(property instanceof StringProperty){
StringProperty stringProperty = (StringProperty)property;
List<String> enums = stringProperty.getEnum();
if(CollectionUtils.isNotEmpty(enums)){
type = "enum" + " (" + StringUtils.join(enums, ", ") + ")";
}else{
type = property.getType();
}
}
else{
if(StringUtils.isNotBlank(property.getFormat())){
type = property.getType() + " (" + property.getFormat() + ")";
}else{
type = property.getType();
}
}
return type;
}
}