swagger2markup / swagger2markup Goto Github PK

A Swagger to AsciiDoc or Markdown converter 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.

License: Apache License 2.0

Java 100.00%

api asciidoc documentation markdown swagger

swagger2markup's Introduction

Swagger2Markup

Overview

Note	Dear community, unfortunately I can’t maintain Swagger2Markup alone anymore. There are many interesting new topics: 1) Swagger v3 support 2) Fixing bugs 2) Merge Swagger2Markup repositories and create a new multi-module repository. Any help is welcome. Kind regards, Robert

The primary goal of this project 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 Swagger. The result is intended to be an up-to-date, easy-to-read, on- and offline user guide, comparable to GitHub’s API documentation. The output of Swagger2Markup can be used as an alternative to swagger-ui and can be served as static content.
NOTE: The Swagger Specification has been donated to to the Open API Initiative (OAI) and has been renamed to the OpenAPI Specification.

Swagger2Markup converts a Swagger JSON or YAML file into several AsciiDoc or GitHub Flavored Markdown documents which can be combined with hand-written documentation. The Swagger source file can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification. Internally it uses the official swagger-parser and my markup-document-builder.

You can use Swagger2Markup 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 Swagger JAX-RS, springfox or spring-restdocs. If you are Gradle or Maven user, you can also use the Swagger2Markup Gradle Plugin or Swagger2markup Maven Plugin.

AsciiDoc is preferable to Markdown as it has more features. AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to HTML, PDF and EPUB. AsciiDoc is much better suited for describing public APIs than JavaDoc or Annotations.

You can generate your HTML5, PDF and EPUB documentation via asciidoctorj or even better via the asciidoctor-gradle-plugin or asciidoctor-maven-plugin.

The project requires at least JDK 8.

Example

Reference documentation

Contributing

Community contributions

Pull requests are welcome.

Questions

You can ask questions about Swagger2Markup in Gitter.

Bugs

If you believe you have found a bug, please take a moment to search the existing issues. If no one else has reported the problem, please open a new issue that describes the problem in detail and, ideally, includes a test that reproduces it.

Enhancements

If you’d like an enhancement to be made to Swagger2Markup, pull requests are most welcome. The source code is on GitHub. You may want to search the existing issues and pull requests to see if the enhancement is already being worked on. You may also want to open a new issue to discuss a possible enhancement before work on it begins.

Companies who use Swagger2Markup

Deutsche Telekom AG
Restlet — Restlet offers an API platform, covering the design, test and operation of Web APIs, and uses Swagger2Markup to generate appealing HTML documentation from API definitions.
QAware GmbH
AppDirect — The leading commerce platform for selling cloud services.
wescale
TaskAssure
ISAAC
Spreadshirt

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

swagger2markup's People

Contributors

Stargazers

Watchers

Forkers

joensson colmg vicchugu mrose-avenuecode jknack sg-ad izeye mxl creocoder johanhammar i-fimafeng relequestual tschaible jergamb minospong lucboutier raaga123 nagyist nagyistoce pnerger maksimmyshkin christopheroger ruisalgado vinkapoor wesmc7777 rostskadat lcamilo15 erikhakansson travishaagen shaoulov vasanthdharmaraj croger42 glaforge atomfrede crowell eduac zhangzhenhuajack ali5253 lj015625 ryanrutan steffentemplin somas mukundgandlur eltmon birdnofoot bbcmgdm filip-owczarzak catinred2 jfiala ordercloud bkryza yilongyu lionh evonck ruihanzhao mhswisscom gregoriodistefano michaelntech nice-kai kristinagen buzztaiki rafaels-dev rgueldem tecsisa rchargel liangjw whileloop99 jamesbassett krraghavan cleydsonjr dcasas cncap rxcai kevin-dinh buri17 reacherhsu cascer1 fooinha kruffin jbrugge sophea gmousset shardings widmogrod linjisong nobotym jonbo372 teacherpan dmalone87 diamonddocumentation debugfuture carlosduclos jerryzhaoau schibsted brischniz zth390872451 rajkaramchedu jeanclam ztc-dev trasa

swagger2markup's Issues

Multiple entries exception without multiple entries

I get

[ERROR] Failed to execute goal com.redowlanalytics:swagger2markup-maven-plugin:0.7.1:process-swagger (gen-asciidoc) on p
roject if8-server: Execution gen-asciidoc of goal com.redowlanalytics:swagger2markup-maven-plugin:0.7.1:process-swagger
failed: Multiple entries with same key: triggerPassword=io.swagger.models.properties.StringProperty@1b4d89f and triggerP

from a swagger file with the following contents (excerpt):

 "json_sendpoilistrequest" : {
      "type" : "object",
      "title" : "SendPoiListRequest",
      "allOf" : [
        {
          "$ref" : "#/definitions/json_startserviceconfigurationtype"
        },
        {
          "$ref" : "#/definitions/json_startserviceconfigurationtypev2"
        },
        {
          "properties" : {
            "pois" : {
                "description" : "Gets the value of the pois property.\r\n\r\n<p>\r\nThis accessor method returns a reference to the live list,\r\nnot a snapshot. Therefore any modification you make to the\r\nreturned list will be present inside the JAXB object.\r\nThis is why there is not a <CODE>set<\/CODE> method for the pois property.\r\n\r\n<p>\r\nFor example, to add a new item, do as follows:\r\n<pre>\r\n    getPois().add(newItem);\r\n <\/pre>\r\n\r\n\r\n<p>\r\nObjects of the following type(s) are allowed in the list\r\n{@link Poi }",
                "type" : "array",
                "items" : {
                  "$ref" : "#/definitions/json_poi"
                }
            }
          }
        }
      ],
      "description" : "<p>Java class for anonymous complex type.\r\n\r\n<p>The following schema fragment specifies the expected content contained within this class.\r\n\r\n<pre>\r\n &lt;complexType>\r\n   &lt;complexContent>\r\n     &lt;extension base=\"{}StartServiceConfigurationTypeV2\">\r\n       &lt;sequence>\r\n         &lt;element name=\"pois\" type=\"{}Poi\" maxOccurs=\"unbounded\" minOccurs=\"0\"/>\r\n       &lt;/sequence>\r\n     &lt;/extension>\r\n   &lt;/complexContent>\r\n &lt;/complexType>\r\n <\/pre>"
    }


    "json_startserviceconfigurationtypev2" : {
      "type" : "object",
      "title" : "StartServiceConfigurationTypeV2",
      "allOf" : [
        {
          "$ref" : "#/definitions/json_startserviceconfigurationtype"
        },
        {
          "properties" : {
            "endTime" : {
                "description" : "Gets the value of the endTime property.",
                "type" : "number"
            },
            "serviceCommand" : {
                "description" : "Gets the value of the serviceCommand property.",
                "type" : "string"
            },
            "startTime" : {
                "description" : "Gets the value of the startTime property.",
                "type" : "number"
            },
            "token" : {
                "description" : "Gets the value of the token property.",
                "type" : "string"
            },
            "triggerMediaType" : {
                "description" : "Gets the value of the triggerMediaType property.",
                "type" : "string"
            }
          }
        }
      ],
      "description" : "<p>Java class for StartServiceConfigurationTypeV2 complex type.\r\n\r\n<p>The following schema fragment specifies the expected content contained within this class.\r\n\r\n<pre>\r\n &lt;complexType name=\"StartServiceConfigurationTypeV2\">\r\n   &lt;complexContent>\r\n     &lt;extension base=\"{}StartServiceConfigurationType\">\r\n       &lt;sequence>\r\n         &lt;element name=\"triggerMediaType\" type=\"{http://www.w3.org/2001/XMLSchema}string\" minOccurs=\"0\"/>\r\n         &lt;element name=\"token\" type=\"{}String256\"/>\r\n         &lt;element name=\"startTime\" type=\"{http://www.w3.org/2001/XMLSchema}long\" minOccurs=\"0\"/>\r\n         &lt;element name=\"endTime\" type=\"{http://www.w3.org/2001/XMLSchema}long\" minOccurs=\"0\"/>\r\n         &lt;element name=\"serviceCommand\" type=\"{http://www.w3.org/2001/XMLSchema}string\" minOccurs=\"0\"/>\r\n       &lt;/sequence>\r\n     &lt;/extension>\r\n   &lt;/complexContent>\r\n &lt;/complexType>\r\n <\/pre>"
    }


    "json_startserviceconfigurationtype" : {
      "type" : "object",
      "title" : "StartServiceConfigurationType",
          "properties" : {
            "triggerPassword" : {
                "description" : "Gets the value of the triggerPassword property.",
                "type" : "string"
            },
            "triggerUrl" : {
                "description" : "Gets the value of the triggerUrl property.",
                "type" : "string"
            },
            "triggerUserId" : {
                "description" : "Gets the value of the triggerUserId property.",
                "type" : "string"
            }
          },
      "description" : "<p>Java class for StartServiceConfigurationType complex type.\r\n\r\n<p>The following schema fragment specifies the expected content contained within this class.\r\n\r\n<pre>\r\n &lt;complexType name=\"StartServiceConfigurationType\">\r\n   &lt;complexContent>\r\n     &lt;restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\r\n       &lt;sequence>\r\n         &lt;element name=\"triggerUrl\" type=\"{http://www.w3.org/2001/XMLSchema}anyURI\" minOccurs=\"0\"/>\r\n         &lt;element name=\"triggerUserId\" type=\"{http://www.w3.org/2001/XMLSchema}string\" minOccurs=\"0\"/>\r\n         &lt;element name=\"triggerPassword\" type=\"{http://www.w3.org/2001/XMLSchema}string\" minOccurs=\"0\"/>\r\n       &lt;/sequence>\r\n     &lt;/restriction>\r\n   &lt;/complexContent>\r\n &lt;/complexType>\r\n <\/pre>"
    }

Add support of Response Headers

Hi there!

When I add @responseheaders to my classes, their documentation do not show up in the generated markup.

For example:

    @ApiResponses(value = {
            @ApiResponse(
                    code = 201, message = "My message",
                    responseHeaders = {
                            @ResponseHeader(
                                    name = "Location",
                                    description = "The Location Header value")
                    })
    })
  ... etc.

Should this add a new column in the Responses table?

Thanks so much for your help and awesome library. Other than this we love it!

Support for vendor extensions

Hello, sorry if I've missed where this is answered in your docs and/or other issues. What support is there for vendor extensions (properties prefixed x-) in the swagger definition docs?

If none, is there any plan to add support?

Is this something you would accept contributions for?

How To: Sample Request Response

What is your recommandation to do this?

Just include json manual ( the ones we use in the integr. tests) ?
I know that there is some support for generating request response out of Junit tests,
but how to use with swagger2markup ?

Support for dynamic extensions from files to operations

We want to the user provide some new content from files for each operation.

The content will be extracted from files and appended to docBuilder as-is.
Extension name is not significative, so we'll append extensions by sorting extension names by natural order.

We provide a new .withExtensions(String extensionsFolderPath).
The extension folder path contains a structured layout :

<operation(normalized)>
- .adoc
- .md

Extensions must start section leveling at level 1. We'll use http://asciidoctor.org/docs/user-manual/#relative-leveloffset technic to adapt section leveling dynamically (if GroupBy.TAGS is used for example).

Example :

launchcommand
- example1.adoc
- http-request.adoc
- http-response.adoc

example1.adoc :

== Example 1
=== Request
...
=== Response
...

http-request.adoc :

== HTTP Request
...

http-response.adoc :

== HTTP Response
...

You'll notice the only difference with current examples implementation is : you have to include section title in file content

Support composed definitions

Currently, if you have a composed definition (using the allOf device), no documentation is generated for that definition other than the header and description. This is because the current definition code does not take into account $refs or composition.

This adds support for both reference models and composed models. The composition logic could likely be improved to provide better documentation for the composition (i.e. - where the definition came from, etc.), but for this improvement just flattens the composed model in the documentation. I see this is a fine compromise given that's how the endpoint will behave, anyway.

Authentication info isn't included in the markup

I have a Basic Auth blurb in my Swagger JSON, and I can't see it in the resulting Asciidoc output.

Definitions are not sorted alphabetically in the resulting asciidoc

Would be nice to have them sorted automatically and even to have a way to specify custom ordering.

logback.xml on the classpath

Projects swagger2markup and markup-document-builder come with logback.xml on the classpath. For Spring Boot this is default location for logback configuration and Spring Boot uses this logback.xml when there is no logback configuration (defaults from Spring Boot is fine for development purposes).

Clueless on gradle and java, trying to make this work

We have an install of swagger2markup that generates HTML via adoc. I am trying to make it generate markdown (just to evaluate). I have no idea how. I have no experience in Java / Gradle this and all my hacks have failed. Any clues you can offer would be appreciated.

build.gradle:

buildscript {
    repositories {
        mavenLocal()
        jcenter()
    }

    dependencies {
        classpath 'io.github.robwin:swagger2markup:0.8.0'
    }
}

task gendocs << {
  io.github.robwin.swagger2markup.Swagger2MarkupConverter
    .from("./input.json")
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build()
    .intoFolder("./");
  println '*** generating docs to ./'
}

errors:

Selected primary task 'gendocs' from project :
Tasks to be executed: [task ':gendocs']
:gendocs (Thread[main,5,main]) started.
:gendocs
Executing task ':gendocs' (up-to-date check took 0.002 secs) due to:
  Task has not declared any outputs.
reading from ./input.json
no property for v1.Binding, null
no property for v1.Binding, null
no property for v1.ComponentStatusList, null
no property for v1.ComponentStatus, null
no property for v1.EndpointsList, null
no property for v1.Endpoints, null
no property for v1.Endpoints, null
no property for json.WatchEvent, null
no property for v1.Endpoints, null
no property for v1.Endpoints, null
no property for v1.Endpoints, null
no property for unversioned.Patch, null
no property for v1.Endpoints, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.EndpointsList, null
no property for json.WatchEvent, null
no property for v1.EventList, null
no property for v1.Event, null
no property for v1.Event, null
no property for json.WatchEvent, null
no property for v1.Event, null
no property for v1.Event, null
no property for v1.Event, null
no property for unversioned.Patch, null
no property for v1.Event, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.EventList, null
no property for json.WatchEvent, null
no property for v1.LimitRangeList, null
no property for v1.LimitRange, null
no property for v1.LimitRange, null
no property for json.WatchEvent, null
no property for v1.LimitRange, null
no property for v1.LimitRange, null
no property for v1.LimitRange, null
no property for unversioned.Patch, null
no property for v1.LimitRange, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.LimitRangeList, null
no property for json.WatchEvent, null
no property for v1.NamespaceList, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for json.WatchEvent, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for unversioned.Patch, null
no property for v1.Namespace, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for v1.Namespace, null
no property for v1.NodeList, null
no property for v1.Node, null
no property for v1.Node, null
no property for json.WatchEvent, null
no property for v1.Node, null
no property for v1.Node, null
no property for v1.Node, null
no property for unversioned.Patch, null
no property for v1.Node, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.Node, null
no property for v1.Node, null
no property for v1.PersistentVolumeClaimList, null
no property for v1.PersistentVolumeClaim, null
no property for v1.PersistentVolumeClaim, null
no property for json.WatchEvent, null
no property for v1.PersistentVolumeClaim, null
no property for v1.PersistentVolumeClaim, null
no property for v1.PersistentVolumeClaim, null
no property for unversioned.Patch, null
no property for v1.PersistentVolumeClaim, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.PersistentVolumeClaimList, null
no property for json.WatchEvent, null
no property for v1.PersistentVolumeClaim, null
no property for v1.PersistentVolumeClaim, null
no property for v1.PersistentVolumeList, null
no property for v1.PersistentVolume, null
no property for v1.PersistentVolume, null
no property for json.WatchEvent, null
no property for v1.PersistentVolume, null
no property for v1.PersistentVolume, null
no property for v1.PersistentVolume, null
no property for unversioned.Patch, null
no property for v1.PersistentVolume, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.PersistentVolume, null
no property for v1.PersistentVolume, null
no property for v1.PodList, null
no property for v1.Pod, null
no property for v1.Pod, null
no property for json.WatchEvent, null
no property for v1.Pod, null
no property for v1.Pod, null
no property for v1.Pod, null
no property for unversioned.Patch, null
no property for v1.Pod, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.PodList, null
no property for json.WatchEvent, null
no property for v1.Binding, null
no property for v1.Binding, null
no property for *int64, null
no property for *unversioned.Time, null
no property for *int64, null
no property for *int64, null
no property for v1.Pod, null
no property for v1.Pod, null
no property for v1.Pod, null
no property for v1.PodTemplateList, null
no property for v1.PodTemplate, null
no property for v1.PodTemplate, null
no property for json.WatchEvent, null
no property for v1.PodTemplate, null
no property for v1.PodTemplate, null
no property for v1.PodTemplate, null
no property for unversioned.Patch, null
no property for v1.PodTemplate, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.PodTemplateList, null
no property for json.WatchEvent, null
no property for v1.ReplicationControllerList, null
no property for v1.ReplicationController, null
no property for v1.ReplicationController, null
no property for json.WatchEvent, null
no property for v1.ReplicationController, null
no property for v1.ReplicationController, null
no property for v1.ReplicationController, null
no property for unversioned.Patch, null
no property for v1.ReplicationController, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.ReplicationControllerList, null
no property for json.WatchEvent, null
no property for v1.ReplicationController, null
no property for v1.ReplicationController, null
no property for v1.ResourceQuotaList, null
no property for v1.ResourceQuota, null
no property for v1.ResourceQuota, null
no property for json.WatchEvent, null
no property for v1.ResourceQuota, null
no property for v1.ResourceQuota, null
no property for v1.ResourceQuota, null
no property for unversioned.Patch, null
no property for v1.ResourceQuota, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.ResourceQuotaList, null
no property for json.WatchEvent, null
no property for v1.ResourceQuota, null
no property for v1.ResourceQuota, null
no property for v1.SecretList, null
no property for v1.Secret, null
no property for v1.Secret, null
no property for json.WatchEvent, null
no property for v1.Secret, null
no property for v1.Secret, null
no property for v1.Secret, null
no property for unversioned.Patch, null
no property for v1.Secret, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.SecretList, null
no property for json.WatchEvent, null
no property for v1.ServiceAccountList, null
no property for v1.ServiceAccount, null
no property for v1.ServiceAccount, null
no property for json.WatchEvent, null
no property for v1.ServiceAccount, null
no property for v1.ServiceAccount, null
no property for v1.ServiceAccount, null
no property for unversioned.Patch, null
no property for v1.ServiceAccount, null
no property for v1.DeleteOptions, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.ServiceAccountList, null
no property for json.WatchEvent, null
no property for v1.ServiceList, null
no property for v1.Service, null
no property for v1.Service, null
no property for json.WatchEvent, null
no property for v1.Service, null
no property for v1.Service, null
no property for v1.Service, null
no property for unversioned.Patch, null
no property for v1.Service, null
no property for unversioned.Status, null
no property for json.WatchEvent, null
no property for v1.ServiceList, null
no property for json.WatchEvent, null
no property for void, null
WARNING!  No property detected!  Falling back to string!
no property for null, null
no property for null, null
no property for any, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for any, null
no property for any, null
no property for any, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for any, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for any, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for null, null
no property for any, null
no property for null, null
no property for null, null
:gendocs FAILED
:gendocs (Thread[main,5,main]) completed. Took 0.89 secs.

FAILURE: Build failed with an exception.

* Where:
Build file '/build/build.gradle' line: 13

* What went wrong:
Execution failed for task ':gendocs'.
> Could not find property 'MarkupLanguage' on task ':gendocs'.

* Try:
Run with --stacktrace option to get the stack trace. Run with --debug option to get more log output.

BUILD FAILED

Total time: 22.728 secs

Boolean values

Hi @RobWin

I found a weird error, i think is a bug in the swagger-core.

When any model have a "boolean" property it fails to parse the model (from the swagger.json)

The error is

com.fasterxml.jackson.databind.node.BooleanNode cannot be cast to com.fasterxml.jackson.databind.node.TextNode (through reference chain: com.wordnik.swagger.models.ModelImpl["properties"]) (through reference chain: com.wordnik.swagger.models.Swagger["definitions"])
reading from docs/swagger/tpaga_api.json
com.fasterxml.jackson.databind.node.BooleanNode cannot be cast to com.fasterxml.jackson.databind.node.TextNode (through reference chain: com.wordnik.swagger.models.ModelImpl["properties"]) (through reference chain: com.wordnik.swagger.models.Swagger["definitions"])

Any way be used in jdk6 projects?

Swagger2markup is really really fun, coz we don't need to view api docs dynamictly, especially on a production envirement, we prefer to generate static docs any time we want, so swagger2markup will help a lot, I stared this project at the first sight.

Unfortunately all of our projects stay jdk6 because they are big and developed years ago, and I face the jdk compatibility problem when I try to run the swagger2markup unit test method to generate static docs, it's so sad...

Comma should be escapes when constructing table in csv format in asciidoc

e.g.

@ApiModelProperty("My description with comma: a, b, c")
private String someField;

causes a broken table when rendering it to e.g. html.

Errors generating against 1.2 Swagger spec

We are still using Swagger 1.2 because of a regression in Swagger-UI that prevents us from upgrading at this time. I found that the example outlined here https://swagger2markup.readme.io/docs/demo would not work with a 1.2 Swagger definition. So based on the example Gradle script and JUnit test, I created a version that uses SwaggerCompatConverter to parse my file and send the resulting Swagger object to Swagger2MarkupConverter:

Swagger swagger = new SwaggerCompatConverter().read(temp.getAbsolutePath());
Swagger2MarkupConverter
    .from(swagger) 
    .build()
    .intoFolder("src/docs/asciidoc/generated");

When I create the Swagger object, I get a bunch of exceptions logged to standard error, but the JVM does not exit. I reviewed the console output, and I appear to get 1 exception for each endpoint. Here's one example, they all look basically the same:

java.io.FileNotFoundException: /var/folders/g6/plnk0r894t7gd5ch4dkjlttm0000gn/T/repository (No such file or directory)
    at java.io.FileInputStream.open0(Native Method)
    at java.io.FileInputStream.open(FileInputStream.java:195)
    at java.io.FileInputStream.<init>(FileInputStream.java:138)
    at com.fasterxml.jackson.core.JsonFactory.createParser(JsonFactory.java:708)
    at com.fasterxml.jackson.databind.ObjectMapper.readTree(ObjectMapper.java:1846)
    at io.swagger.parser.SwaggerCompatConverter.readDeclaration(SwaggerCompatConverter.java:424)
    at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:125)
    at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:72)
    at com.docfinity.swagger.SwaggerDocGeneratorTests.convertRemoteSwaggerToAsciiDoc(SwaggerDocGeneratorTests.java:96)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50)
    at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
    at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47)
    at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)
    at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:78)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:57)
    at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290)
    at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71)
    at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288)
    at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58)
    at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268)
    at org.junit.runners.ParentRunner.run(ParentRunner.java:363)
    at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)
    at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:459)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:675)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192)

The Swagger2MarkupConverter does complete, but the generated adoc/PDFs are mostly empty and just contain boilerplate stuff like table of contents; none of my API is included.

Here is a gist of my 1.2 swagger definition: https://gist.github.com/rdiehl/3d2405bbcf08006aecb1

Is this something I need to pass along to the swagger-parser project?

enum definitions show up empty in definitions.adoc

I have an enum that is referenced in models that looks as follows:

       "mode": {
            "description": "mode",
            "enum": [
                false,
                true
            ],
            "type": "string"
        },

This entry shows up empty in definitions.adoc file

Descriptions are treated as AsciiDoc?

Hi,

Swagger spec says that some descriptions can be written in GFM syntax.
swagger2markup seems to preserve those descriptions as-is, so they are broken as AsciiDoc.
I hope that swagger2markup will covert descriptions from GFM to AsciiDoc.

Example input: http://petstore.swagger.io/v2/swagger.json

Thanks.

Refactor separated documents logic to support inter-document cross-references

Context :
Currently, s2m supports all-in-one document (.asString) or 3 (overview+paths+definitions) documents (.intoFolder() ).
Some extra options (.withSeparatedDefinitions, withSeparatedPaths) create "supplementary" documents without impact on others documents.

Functional :
I'd like cross-references to become inter-documents cross-references, when I generate multiple documents.
This way, AsciiDoc will continue to work as currently when 3 documents are included in a single one. But the links will work too when documents will be independently rendered as multiple HTMLs files.

Problem :
Generated cross-references can only address one generation model at a time :

all-in-one : all cross-refs are local
3 documents : cross-refs to definitions are Xrefs to ./definitions.adoc
separated definitions : cross-refs to definitions are Xrefs to each generated definition file

Proposal :
For consistency, when using separated files (withSeparatedDefinitions or withSeparatedPaths), we should not generate original paths.adoc and definitions.adoc files, and Xrefs are always inter-document XRefs to each definition file.
If you want to generate the 3 docs too, you'll have to relaunch the builder with different options.

Corollary:
When using Markdown output, all Xrefs should be disabled in all modes except the all-in-one mode (.asString() ) because Markdown does not support inter-documents Xrefs.

Slate markdown

The generated markdown look ugly in slate.

Would be beautiful a new markup type, that is SLATE and is a markdown for slate =D

Paths should always be sorted when not displayed "as-is"

I propose to introduce custom comparators to sort all resources :

paths
definitions
tags
path methods

Default ordering is set to Ordering.natural() by default.
Swagger as-is ordering is possible setting comparator to null

Splitting Swagger object descriptions

Hi Robert,

This is a suggestion for enhancement. In addition to the definitions.adoc that gets generated, I would like to generate individual files for each object (ex: person.adoc, address.adoc, purchase.adoc ...). I'd like to reference the model from a separate document that I've written, but I would like to include the object definitions individually in specific sections rather than in a single section. Do you think this would be something useful? I haven't dived into the code yet, but I'd be willing to take a stab at it. Do you think it would be something horribly difficult as the design stands, and would it be something possibly useful to others?

Thanks!

Sebastien

Inline schemas support

It seems inline schemas are not as detailed as references to global definitions.

The following swagger both reference inline schemas (Request and Response) and a global definition (ComplexObject) :

swagger: "2.0"
info:
  title: Test
paths:
  /path1:
    post:
      description: Path 1
      tags:
        - all
      parameters:
        - name: Request
          in: body
          schema:
            type: object
            properties:
              param1:
                description: Param 1
                $ref: '#/definitions#ComplexObject'
              param2:
                description: Param 2
                type: string
      responses:
        200:
          description: Response
          schema:
            type: object
            properties:
              generatedId:
                description: Generated id
                type: string
definitions:
  ComplexObject:
    type: object
    properties:
      volumeId:
        description: Volume id
        type: string

The result is :

The schema of Request and Response is just "object".

I propose to add a local section "Definitions" to each path, next to "Description", "Parameters" and "Responses" sections.
Then, detail local objects (like in the global definitions), and create a local cross-reference to them :

One problem, though, is with the link to the local definition, because local parameters names are not globally unique.

unknown format not supported for properties

My definitions contains string properties of "user-defined" formats, e.g. "email" below. According to 2.0 spec, this is valid.

"Order":{
 "properties": {
                "emailAddr": {
                    "type": "string",
                    "format": "email"
                }
            }
}

When this is encountered, I receive an exception:

java.lang.reflect.InvocationTargetException
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:606)
    at org.springframework.boot.loader.MainMethodRunner.run(MainMethodRunner.java:53)
    at java.lang.Thread.run(Thread.java:745)
Caused by: java.lang.NullPointerException
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definition(DefinitionsDocument.java:110)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definitions(DefinitionsDocument.java:73)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.build(DefinitionsDocument.java:57)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.buildDocuments(Swagger2MarkupConverter.java:92)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.intoFolder(Swagger2MarkupConverter.java:72)
    at com.mycompany.app.App.main(App.java:38)
    ... 6 more

Render examples of response and schema objects

See PR #71

Parser does not like remote URL path with curly braces

Not sure if this is an issue with this project or not. I am a novice. My API reads just fine for remote URL paths that do not have curly braces in them, however this occurs when they do. Apologies for the oversimplification, but this is all I can come up with:

java.io.IOException: Server returned HTTP response code: 500 for URL: http://localhost:8080/Walletron/api/api-docs/ver1/brands/{brand}/templates
at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1626)
at io.swagger.parser.util.RemoteUrl.urlToString(RemoteUrl.java:46)
at io.swagger.parser.SwaggerCompatConverter.readDeclaration(SwaggerCompatConverter.java:367)
at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:104)
at io.swagger.parser.SwaggerParser.read(SwaggerParser.java:34)
at io.swagger.parser.SwaggerParser.read(SwaggerParser.java:14)
at io.github.robwin.swagger2markup.Swagger2MarkupConverter$Builder.(Swagger2MarkupConverter.java:88)
at io.github.robwin.swagger2markup.Swagger2MarkupConverter.from(Swagger2MarkupConverter.java:49)
at io.github.robwin.swagger2markup.Swagger2MarkupConverterTest.testSwagger2AsciiDocConverter(Swagger2MarkupConverterTest.java:18)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:606)
...

This repeats again and again for similar URLs, but the markdown is produced nicely for those paths without a parameter.

Add discriminator field to the output

To support Polymorphism the field discriminator should be rendered.

Definitions that use polymorphism causes exception: Multiple entries with same key

I originally logged this in swagger-core, and they advised me the issue was likely in swagger2markdown. We have a number of models that use polymorphism, some of them extend multiple levels. We're using Java annotations and the JAX-RS integration to create our Swagger definition at runtime. I'm running into issues running our spec through the swagger2markup tool. Here's our Java classes with the swagger annotations.

@ApiModel(description = "The representation of a Chart-like object.", discriminator = "_class",
        subTypes = { TextChartDTO.class, ChartDTO.class, TableChartDTO.class })
public abstract class ChartableDTO implements Serializable {
    private String id;
    private String name;
    public String getId() { return id;}
    public void setId(final String id) {this.id = id;}
    public String getName() { return name;}
    public void setName(final String name) {this.name = name};
    // Various other properties
}

@ApiModel(description = "A parent class for all charts.", parent = ChartableDTO.class, discriminator = "_class",
        subTypes = { PieChartDTO.class, BarChartDTO.class, AreaChartDTO.class, LineChartDTO.class,
            MixedChartDTO.class, GaugeChartDTO.class })
public abstract class ChartDTO extends ChartableDTO implements Serializable {
    private ChartType chartType;
    public ChartType getChartType() {return chartType;}
    public void setChartType(final ChartType type) {this.chartType = type;}
    // various other properties
}

@ApiModel(description = "An area chart.", parent = ChartDTO.class)
public class AreaChartDTO extends ChartDTO implements Serializable {
    // various properties
}

When our swagger definition is generated, the definition for AreaChartDTO looks like this:

"AreaChartDTO": {
"allOf": [
{
"$ref": "#/definitions/ChartDTO"
},
{
"type": "object",
"properties": {
  "id": {
    "type": "string"
  },
  "name": {
    "type": "string"
  },
},
.... more stuff

Note the existence of "allOf", referencing the ChartDTO definition, and then individual properties like "id" and "name". The definition for ChartDTO looks like this:

"ChartDTO": {
"allOf": [
{
"$ref": "#/definitions/ChartableDTO"
},
{
"type": "object",
"properties": {
  "id": {
    "type": "string"
  },
  "name": {
    "type": "string"
  },
.... more stuff

Again note that id and name are defined here. The definition for ChartableDTO has them as well. In effect what we're seeing is that properties from the base classes are being duplicated for each concrete class. The full generated swagger is here: https://gist.github.com/rdiehl/6969b15f682387438662

When the swagger definition goes through the swagger-parser, it parses successfully. When I send the Swagger object that comes back from the parser into the Swagger2markup tool, it throws an exception about having multiple entries with the same key: "id".

java.lang.IllegalArgumentException: Multiple entries with same key: id=io.swagger.models.properties.StringProperty@3729f557 and id=io.swagger.models.properties.StringProperty@3729f557
    at com.google.common.collect.ImmutableMap.checkNoConflict(ImmutableMap.java:150)
    at com.google.common.collect.RegularImmutableMap.checkNoConflictInBucket(RegularImmutableMap.java:104)
    at com.google.common.collect.RegularImmutableMap.<init>(RegularImmutableMap.java:70)
    at com.google.common.collect.ImmutableMap$Builder.build(ImmutableMap.java:254)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:232)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:217)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:226)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.propertiesSection(DefinitionsDocument.java:188)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definition(DefinitionsDocument.java:184)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definitions(DefinitionsDocument.java:134)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.build(DefinitionsDocument.java:111)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.buildDocuments(Swagger2MarkupConverter.java:120)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.intoFolder(Swagger2MarkupConverter.java:98)
    at com.docfinity.swagger.SwaggerDocGeneratorTests.convertRemoteSwaggerToAsciiDoc(SwaggerDocGeneratorTests.java:98)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50)
    at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
    at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47)
    at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)
    at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:78)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:57)
    at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290)
    at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71)
    at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288)
    at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58)
    at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268)
    at org.junit.runners.ParentRunner.run(ParentRunner.java:363)
    at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:86)
    at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:459)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:675)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192)

I briefly looked at the code, it seems like the use of ImmutableMap.Builder is inconsistent with how Swagger implements "allOf".

Spring MVC integration example

Hi,

I was wondering if you could provide an integration example without Spring Boot. It would be very useful for new users. Until now I could not get it to work.

Karens

Some sections should be broken into separate lines

swagger2markup generates the following URI scheme information:

=== URI scheme
Host: example.com
BasePath: /api
Schemes: HTTPS

However, because these lines are not hard returns, the actual interpretation of these lines is:

URI scheme
Host: example.comBasePath: /apiSchemes: HTTPS

This makes for some unsightly output when using asciidoctor to convert the adoc to HTML.

How do we change the output which swagger2markup chooses, in order to customize the newlines for this section, and other sections like it?

I'd like the section to render adocs which use the + symbol, signifying a hard break:

=== URI scheme
Host: example.com +
BasePath: /api +
Schemes: HTTPS +

References Not Recognized in Response

Using the Swagger 2.0 spec, if i have a set of global responses as follows:

responses:
  Not Found:
    description: Not Found
    schema:
      type: object
      $ref: '#/definitions/Error'

and then reference them later in a path as follows:

  responses:
    '400':
      $ref: '#/responses/Bad Request'

I get the following output (asciidoc)

==== Responses
[options="header"]
|===
|HTTP Code|Description|Schema
|400|null|No Content
|===

It would be great if the referenced response was picked up, and the description and the schema were included in the output.

Can't convert Swagger document containing nested arrays

I have a Swagger document containing nested arrays and when converting it it fails with a null pointer: java.lang.NullPointerException: property must not be null!

Here's an example Swagger file that will fail

swagger: '2.0'

info:
  version: "0.0.1"
  title: Nested arrays
  description: Demo of nested arrays
  contact:
    name: Johan Hammar

host: localhost

schemes:
  - https

basePath: /v1
produces:
  - application/json
consumes:
  - application/json

paths:
  /demo:
    get:
      tags:
        - Demo
      summary: Nested arrays demo
      description: |

      responses:
        200:
          description: Nested array object
          schema:
            type: object
            $ref: '#/definitions/nested'
definitions:              
  nested:
    properties:
      nested_array:
        type: array
        items: 
          properties:
            first_value:
              type: string
            second_value:
              type: string

However if I split the inner model to it's own model and reference it from the outer array it works.

...
nested:
    properties:
      nested_array:
        type: array
        items:
          $ref: '#/definitions/inner'
  inner:
    properties:
            first_value:
              type: string
            second_value:
              type: string

I'm not sure if the first example is valid but it does render correctly in the Swagger editor

/ not escaped

The following in Swagger:

"produces": [
    "*/*"
]

...results in this asciidoc:

==== Produces

* */*

...which is rendered as a bold slash.

MarkupLanguage cannot be resolved to a variable

Hi,

Great library! I am trying to integrate it with swagger-springmvc 1.0 and spring 3.2.
From your example application the class MarkupLanguage (io.github.robwin.swagger2markup.builder.markup.MarkupLanguage) does not seem to exist in the maven package.

Moreover and maybe related, I get the following error message in pom.xml:
Missing artifact io.github.robwin:markup-document-builder:jar:0.1.0
I see that this version is already removed from the repository, but is still a dependency in build.gradle file.

Looking forward to integrate it with my solution.

Karens

Exception: Multiple entries with same key

I have a Swagger Specification with a model where one definition includes another definition. In addition, the two definitions have a parameter by the same name. If I run this Swagger Specification through Swagger2Markup, I get a Multiple entries with same key exception.

See this:

[BASH]# java -jar ./libs/swagger2markup-cli-0.0.1.jar generate -i ex.yaml -o s2m -l asciidoc
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
reading from ex.yaml
Exception in thread "main" java.lang.IllegalArgumentException: Multiple entries with same key: propA=io.swagger.models.properties.StringProperty@1b4d89f and propA=io.swagger.models.properties.StringProperty@1b4d89f
    at com.google.common.collect.ImmutableMap.checkNoConflict(ImmutableMap.java:150)
    at com.google.common.collect.RegularImmutableMap.checkNoConflictInBucket(RegularImmutableMap.java:104)
    at com.google.common.collect.RegularImmutableMap.<init>(RegularImmutableMap.java:70)
    at com.google.common.collect.ImmutableMap$Builder.build(ImmutableMap.java:254)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:210)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.propertiesSection(DefinitionsDocument.java:172)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definition(DefinitionsDocument.java:168)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definitions(DefinitionsDocument.java:124)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.build(DefinitionsDocument.java:107)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.buildDocuments(Swagger2MarkupConverter.java:150)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.intoFolder(Swagger2MarkupConverter.java:128)
    at me.ledin.swagger2markup.Application$Generate.run(Application.java:66)
    at me.ledin.swagger2markup.Application.main(Application.java:17)

I need to be able to declare the same property name in the two definitions; mostly because I need the documentation of the two properties to be a little bit different (small, yet important, difference).

The issue can be reproduced with the following example:

swagger: '2.0'
info:
  description: TODO
  version: 0.0.1
  title: API Spec
  termsOfService: TODO
basePath: /v1
schemes:
  - http
paths:
  /aaa:
    post:
      tags:
        - AAA
      summary: TODO
      description: TODO
      operationId: aaa
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: TODO
          required: true
          schema:
            $ref: '#/definitions/AAA'
      responses:
        '200':
          description: Success
        '405':
          description: Invalid data
definitions:
  AAA:
    allOf:
      - $ref: '#/definitions/BBB'
      - type: object
        properties:
          propA:
            type: string
          propB:
            type: string
  BBB:
    type: object
    properties:
      propA:
        type: string

responseModel from api declaration is not rendered

Here is json path to responseModel : /apis[*]/operations[*]/responseMessages[*]/responseModel
It would be nice if this responseModel would be link to model in definitions section.

Tag descriptions rendered as tags

Given a Swagger spec with:

"tags": [
    {
        "name": "foo",
        "description": "Foo"
    },
    {
        "name": "bar",
        "description": "Bar"
    }
]

The generated asciidoc has this redundant list of tags:

=== Tags

* foo: Foo
* foo
* bar: Bar
* bar

Support for separate path files

Currently, it's possible to create separate definition files.
It's interesting to support the same feature for paths.
Options :

1 file per path
1 file per tag

How to use asciidoc to combine paths.adoc and definitions.adoc (with toc) as in the example

Hi,

I was wondering how you've produced the example with asciidoctor. I'm not familiar with the tool so would be kind to include provide a CLI or plugin based example of how to do this.

Tuomas

Override/disable "URI scheme"

When using an integration test to generate asciidocs, the "host" is always "localhost". Should be able to override that, or at least disable the "URI scheme" section in the output.

Missing usage documentation

How do I use it?

Dependency not available in Maven repository

Hello,

the swagger2markup dependency is not available in the http://oss.jfrog.org/ repository.
Only the io/swagger2markup folder exists.

Cross-reference in Security subsection of a path element refers to invalid Security Section 's anchor

2 problems:

It seems that the PathsDocument.securitySchemeSection() does not generate the proper cross-reference. This cross-reference points to the Security Section of the corresponding name. The anchor is generated with an underscore while the cross-reference is not.
Furthermore the code does not seem to work properly when generating several documents, as the cross-reference always point to the same document (the current one).

Definitions links in generated markup

Hello,

When I generate Markdown or AsciiDoc from a swagger spec file, no links are generated to directly go to the definitions from paths parameters or responses.

However it seems these links exists when using the spring-swagger2markup-demo (generating HTML from code).
What am i missing ?

@ApiModelProperty metadata are ignored for definitions file

@ApiModelProperty("My description")
private String myField;

results in

"MyType": {
"description": "",
"id": "MyType",
"properties": {
"myField": {
"description": "My description",
"required": false,
"type": "string"
},
...

and is ignored when creating definitions file.

Multi language support

Text should be configurable via language-specific property files.

Missing format for arrays

Given the following Swagger spec for a parameter:

"schema": {
  "type": "array",
  "items": {
    "type": "string",
    "format": "byte"
  }
}

...I'd expect the generated docs to show something like "string (byte) array", but I get "string array".

Optionally isolate body display from other parameters

I propose to introduce an option to change the way body parameter is displayed.
The display is more friendly and well-spaced for APIs with a lot of operations using body parameters.

Before :

After :

Default : No prefix

Error generating against 2.0 spec

Using a Swagger 2.0 compatible spec, I'm getting an error when trying to build the docs. Here is my code:

Swagger2MarkupConverter
    .from(temp.getAbsolutePath()) 
    .build()
    .intoFolder("src/docs/asciidoc/generated");

This is the error that is generated:

java.lang.IllegalArgumentException: Multiple entries with same key: id=io.swagger.models.properties.StringProperty@1b4d89f and id=io.swagger.models.properties.StringProperty@1b4d89f
    at com.google.common.collect.ImmutableMap.checkNoConflict(ImmutableMap.java:150)
    at com.google.common.collect.RegularImmutableMap.checkNoConflictInBucket(RegularImmutableMap.java:104)
    at com.google.common.collect.RegularImmutableMap.<init>(RegularImmutableMap.java:70)
    at com.google.common.collect.ImmutableMap$Builder.build(ImmutableMap.java:254)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:210)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:195)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.getAllProperties(DefinitionsDocument.java:204)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.propertiesSection(DefinitionsDocument.java:172)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definition(DefinitionsDocument.java:168)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.definitions(DefinitionsDocument.java:124)
    at io.github.robwin.swagger2markup.builder.document.DefinitionsDocument.build(DefinitionsDocument.java:107)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.buildDocuments(Swagger2MarkupConverter.java:150)
    at io.github.robwin.swagger2markup.Swagger2MarkupConverter.intoFolder(Swagger2MarkupConverter.java:128)
    at com.docfinity.swagger.SwaggerDocGeneratorTests.convertRemoteSwaggerToAsciiDoc(SwaggerDocGeneratorTests.java:99)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50)
    at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
    at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47)
    at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)
    at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:78)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:57)
    at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290)
    at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71)
    at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288)
    at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58)
    at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268)
    at org.junit.runners.ParentRunner.run(ParentRunner.java:363)
    at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)
    at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:459)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:675)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192)

This is a gist of the 2.0 version of my swagger.json: https://gist.github.com/rdiehl/55630bd808c743237417