swagger2markup / spring-swagger2markup-demo Goto Github PK

A demo project template using Swagger2Markup, Spring Boot, Springfox and spring-restdocs

Java 100.00%

spring-swagger2markup-demo'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.

spring-swagger2markup-demo's People

Contributors

Stargazers

Watchers

Forkers

colmg sg-ad glaforge shayaya majescoindia cristiano-andrade ali5253 zscgrhg ryanrich akurdyukov atomfrede swifthorseman payne lucasmorano digvijaykatoch krraghavan rm3l 1512451239 hanhongyuan wangsan javacspring jgatcher adoignies pvijay127 tlilyanova dimka18belarus yang66 wysedyqmy ocarnia mgivney tiancaijiefu bruce-conan teacherpan sky01126 wilemo mowanjiru wwj912790488 maol74 zth390872451 kwanccc tigermoon masch712 jasonhao123 rgonzaleza voz salilgeorge zhangzhong1018 xushsh163 wyhw ymxk arnaldocaetano chinahappyking andyflatt derektiffany zhongshuiyuan gernd yanhaizhe wudongqiang safibaig moschan guslep xlijun felipe107896 tsunamiwei toothfish 7040210 leandromsa sin-ning vballada slumduck bzzhang shelleeboo ihoney ryanhoho m-alexsupertramp caijunjun penghaihang dikodinovic pear2015 luamas springlet sixyearsinfebruary wuwei1024 xuzchu amitpatelmp githuyong gitzl wollender shafqatshafi zhangqidong waj615 hjsw1 wenzisay huang054 akgcodebrew erickwang inkstarone xpalive honestant hongyan789

spring-swagger2markup-demo's Issues

snippets not included

Hi~ I pull this project,and execute "mvn test". It successfully generated html and pdf files.
But the snippets not included. How to solve it? Thank you very much.

PDF not generated - Maven

Hello,

I'm trying to generate html5 and PDF with maven package ascii......in your own project
That's ok with html, curl but maven can't continu with outputpdf. I have this:

[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-html) @ spring-swagger2markup-demo ---
io/console not supported; tty will not be manipulated
[INFO] Rendered D:\spring-swagger2markup-demo-master\src\docs\asciidoc\index.adoc
[INFO]
[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-pdf) @ spring-swagger2markup-demo ---
io/console not supported; tty will not be manipulated
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20.175s
[INFO] Finished at: Fri Jun 17 10:18:57 GMT+01:00 2016
[INFO] Final Memory: 45M/312M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.asciidoctor:asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-pdf) on project spring-swagger2markup-demo: Execution output-pdf of goal org.asciidoctor:asciidoctor-maven-plugin:1.5.3:process-asciidoc failed: (Errno::ENOENT) C:/Users/ptotaro/.m2/repository/org/asciidoctor/asciidoctorj-pdf/1.5.0-alpha.10.1/asciidoctorj-pdf-1.5.0-alpha.10.1.jar!D:/gems/addressable-2.3.8/data/unicode.data -> [Help 1]
[ERROR]

I saw that it can come from a version problem with asciidoctor-J
do you have an idea ?
thx

Project not building

Hi @RobWin,

Again looks like there is an issue with some dependecy, project not building.


./gradlew check
:compileJava

FAILURE: Build failed with an exception.

* What went wrong:
Could not resolve all dependencies for configuration ':compile'.
> Could not resolve io.springfox:springfox-spi:unspecified.
  Required by:
      io.github.robwin:spring-swagger2markup-demo:1.0.2 > io.springfox:springfox-swagger2:2.0.1-SNAPSHOT
   > Could not resolve io.springfox:springfox-spi:unspecified.
      > Could not get resource 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-spi/unspecified/springfox-spi-unspecified.pom'.
         > Could not GET 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-spi/unspecified/springfox-spi-unspecified.pom'. Received status code 409 from server: Conflict
> Could not resolve io.springfox:springfox-schema:unspecified.
  Required by:
      io.github.robwin:spring-swagger2markup-demo:1.0.2 > io.springfox:springfox-swagger2:2.0.1-SNAPSHOT
   > Could not resolve io.springfox:springfox-schema:unspecified.
      > Could not get resource 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-schema/unspecified/springfox-schema-unspecified.pom'.
         > Could not GET 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-schema/unspecified/springfox-schema-unspecified.pom'. Received status code 409 from server: Conflict
> Could not resolve io.springfox:springfox-swagger-common:unspecified.
  Required by:
      io.github.robwin:spring-swagger2markup-demo:1.0.2 > io.springfox:springfox-swagger2:2.0.1-SNAPSHOT
   > Could not resolve io.springfox:springfox-swagger-common:unspecified.
      > Could not get resource 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-swagger-common/unspecified/springfox-swagger-common-unspecified.pom'.
         > Could not GET 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-swagger-common/unspecified/springfox-swagger-common-unspecified.pom'. Received status code 409 from server: Conflict
> Could not resolve io.springfox:springfox-spring-web:unspecified.
  Required by:
      io.github.robwin:spring-swagger2markup-demo:1.0.2 > io.springfox:springfox-swagger2:2.0.1-SNAPSHOT
   > Could not resolve io.springfox:springfox-spring-web:unspecified.
      > Could not get resource 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-spring-web/unspecified/springfox-spring-web-unspecified.pom'.
         > Could not GET 'http://oss.jfrog.org/artifactory/oss-snapshot-local/io/springfox/springfox-spring-web/unspecified/springfox-spring-web-unspecified.pom'. Received status code 409 from server: Conflict

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

BUILD FAILED

Total time: 11.596 secs

Gradle not running

Hi @RobWin

I checked latest rev (ba9e90a) and runned ./gradlew and I get this error.

:10:08.977 [ERROR] [org.gradle.BuildExceptionReporter] 
22:10:08.979 [ERROR] [org.gradle.BuildExceptionReporter] FAILURE: Build failed with an exception.
22:10:08.979 [ERROR] [org.gradle.BuildExceptionReporter] 
22:10:08.980 [ERROR] [org.gradle.BuildExceptionReporter] * Where:
22:10:08.980 [ERROR] [org.gradle.BuildExceptionReporter] Build file '/home/sortiz/dev_local/tpaga/contrib/spring-swagger2markup-demo/build.gradle' line: 19
22:10:08.981 [ERROR] [org.gradle.BuildExceptionReporter] 
22:10:08.981 [ERROR] [org.gradle.BuildExceptionReporter] * What went wrong:
22:10:08.982 [ERROR] [org.gradle.BuildExceptionReporter] A problem occurred evaluating root project 'spring-swagger2markup-demo'.
22:10:08.982 [ERROR] [org.gradle.BuildExceptionReporter] > io/github/robwin/swagger2markup/Swagger2MarkupPlugin : Unsupported major.minor version 52.0
22:10:08.982 [ERROR] [org.gradle.BuildExceptionReporter] 
22:10:08.983 [ERROR] [org.gradle.BuildExceptionReporter] * Try:
22:10:08.983 [ERROR] [org.gradle.BuildExceptionReporter] Run with --stacktrace option to get the stack trace. 
22:10:08.984 [LIFECYCLE] [org.gradle.BuildResultLogger] 
22:10:08.984 [LIFECYCLE] [org.gradle.BuildResultLogger] BUILD FAILED
22:10:08.985 [LIFECYCLE] [org.gradle.BuildResultLogger] 
22:10:08.985 [LIFECYCLE] [org.gradle.BuildResultLogger] Total time: 2.76 secs

I check the plugin code and looks right in the repo, but i'm not sure if that is the same code in the bintray repo. Can you please check.

Thank you,

Wrong path configuration property for snippets folder - maven

Hi,

i think that there is a problem in the pom.xml file, the snippet files are not being included. The cause could be the property in the row 23 that is:

<swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>

and the solution should be:

<swagger.snippetOutput.dir>${project.basedir}/build/asciidoc/snippets</swagger.snippetOutput.dir>

This is happening because the annotation AutoConfigureRestDocs of Swagger2MarkupTest.java points to

build/asciidoc/snippets

I have no idea through if this problem is present inside the graddle build too.

Execution failed for task ':test'.

java -version
java version "11" 2018-09-25
Java(TM) SE Runtime Environment 18.9 (build 11+28)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11+28, mixed mode)

> Task :test
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.springframework.cglib.core.ReflectUtils$1 (file:/Users/jasonb/.gradle/caches/modules-2/files-2.1/org.springframework/spring-core/4.3.2.RELEASE/fd2f3cf45d3c84f293cb7ee3ab7d24c979495552/spring-core-4.3.2.RELEASE.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain)
WARNING: Please consider reporting this to the maintainers of org.springframework.cglib.core.ReflectUtils$1
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

io.github.robwin.swagger2markup.petstore.Swagger2MarkupTest > createSpringfoxSwaggerJson FAILED
    java.lang.IllegalStateException
        Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException
            Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException
                Caused by: org.springframework.beans.factory.BeanCreationException
                    Caused by: org.springframework.beans.BeanInstantiationException
                        Caused by: org.springframework.beans.factory.BeanCreationException
                            Caused by: java.lang.NoClassDefFoundError
                                Caused by: java.lang.ClassNotFoundException

io.github.robwin.swagger2markup.petstore.Swagger2MarkupTest > addANewPetToTheStore FAILED
    java.lang.IllegalStateException
        Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException
            Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException
                Caused by: org.springframework.beans.factory.BeanCreationException
                    Caused by: org.springframework.beans.BeanInstantiationException
                        Caused by: org.springframework.beans.factory.BeanCreationException
                            Caused by: java.lang.NoClassDefFoundError
                                Caused by: java.lang.ClassNotFoundException

2 tests completed, 2 failed

> Task :test FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test'.
> There were failing tests. See the report at: file:///Users/jasonb/Self/work/spring-swagger2markup-demo/build/reports/tests/test/index.html

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 4s
6 actionable tasks: 6 executed

SpringBoot not working

Hi, @RobWin

I've been unable to boot the app.

I use the run or the runBoot tasks, after run the jar task to generate the html and pdf and I always get this.

Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.
Wed May 20 11:14:14 COT 2015
There was an unexpected error (type=Not Found, status=404).
No message available

pom.xml

the grnerate of pdf will get an error
need to specified the jruby version
<plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.3</version>  <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-pdf</artifactId> <version>1.5.0-alpha.11</version> </dependency> <dependency> <groupId>org.jruby</groupId> <artifactId>jruby-complete</artifactId> <version>1.7.21</version> </dependency> </dependencies> ........

Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin

Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.2.0:convertSwagger2markup (default) on project spring-swagger2markup-demo: Failed to execute goal 'convertSwagger2markup'

JCenter is only available over HTTPS.

the repositories in pom.xml should be update to HTTPS

new package api not scanned

hi,
1: if i change the current package name 'io,github' to 'com.github' ,there will not show any api, even if i add the '.select()
.apis(RequestHandlerSelectors.basePackage("com.github"))' in swagger config.
2: the 'swagger-ui.html' url is avaliable to debug json request?
thks1

Execute “mvn clean test” when dataType is date ,An error occurred

It is normal to change java.util.Date to string. Can you just fill in the basic type here? Thank you for your help.

build tasks not running

Probably there is a problem with re-running convertSwagger2markup and/or asciidoctor after updating rest api annotations. What works for me is adding inputs.files like this:

convertSwagger2markup {
    dependsOn test
    inputs.files(swaggerOutputDir)

    swaggerInput "${swaggerOutputDir}/swagger.json"
    outputDir asciiDocOutputDir
    config = [
            'swagger2markup.pathsGroupedBy' : 'TAGS',
            'swagger2markup.extensions.springRestDocs.snippetBaseUri': snippetsOutputDir.getAbsolutePath(),
            'swagger2markup.outputLanguage':'PL'
    ]
}

asciidoctor {
    dependsOn convertSwagger2markup
    inputs.files( asciiDocOutputDir )
    logDocuments true
    sources {
        include 'index.adoc'
    }
    backends = ['html5', 'pdf']
    attributes = [
            doctype: 'book',
            toc: 'left',
            toclevels: '3',
            numbered: '',
            sectlinks: '',
            sectanchors: '',
            hardbreaks: '',
            generated: asciiDocOutputDir
    ]
}

Documentation not available when demo is started via gradle bootRun

This is rather a question than an issue:

Why is it not possible to access the generated static docs when the demo is started via gradle(w) bootRun?

Is is somehow possible?

it looks we need many dependencies for the pom.xml

it looks we need many dependencies for the pom.xml ，can you support a easy way to use this tool

Cannot use dedicated Spring profile for generating docs

I'm trying to use a dedicated Spring profile for running the tests that generate documentation and it proved to be unsuccessful, no matter what I tried.

Applying

@ActiveProfiles("docs")

causes Spring to select the docs profile
The following profiles are active: docs
but the configuration applied is the one in application.yml not the one in application-docs.yml.
Adding

@TestPropertySource(locations="classpath:application-docs.yml")

I end up with the same result. I have placed application-docs.yml in both main and test source sets, just to be sure, and the settings inside are still not being picked up.

Any ideas on how to override the default settings in application.yml with custom settings specific to documentation generation?

can i add some logic when create acsiidoc file from json file?

@RobWin Hi,

I have a spring boot project, and we have created API document by springfox.
But we need to add further information to the API document.
*further information: response message, description of parameter
One way we can add this information to source code by annotation, but the workload of this way is heavy and so many duplicate works is there.
When I found this demo, which exchanges JSON (created in /v2/api-docs) to markdown/acsiidoc, I think whether I can add some logic to add the further information when the exchange is executing. Or whether I can add the further information into JSON (swagger specification) before the exchange.
I want to find the code for exchange logic but failed. Is exchange done by jar?
Would you tell me where the logic of exchange JSON to markdown/acsiidoc is?
Is it feasibility to add logic to where the logic of exchange is?

Best Regards,
Fly

could you tell me where you set the property `io.springfox.staticdocs.outputDir`

hello,there! I copy your pom and reduce your dependencies into two

<!--Spring-fox dependency-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

and copy all your plugins and properties setting in pom.xml,and write a HelloController with an simple hello.

So basically,I have three questions

swagger.yml under the src/main/test is auto-generated or hand-written?
under your test class,a code snippet is writing the http://localhost:8080/v2/api-docs responses
into swagger/swagger.json,where did you set the property io.springfox.staticdocs.outputDir

    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        //String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();

        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        System.out.println("outputDir="+outputDir);
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andReturn();

        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
            writer.write(swaggerJson);
        }
    }

I get a null in test case.

 @RequestMapping("/hello")
    @ApiOperation(value = "Find pet by ID")
    public String getHello(){
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        System.out.println("outputDir="+outputDir);
        return "hello";
    }

Pdf is not generated

Hello:
I am following the same code which is in the demo repository. I am able to generate the .adoc file but PDF file is not generated.
Following is my gradle settings


test {
    systemProperty 'io.springfox.staticdocs.outputDir', swaggerOutputDir
}

convertSwagger2markup {
    dependsOn test
    inputDir swaggerOutputDir
    pathsGroupedBy io.github.robwin.swagger2markup.GroupBy.TAGS
}

asciidoctor {
    dependsOn convertSwagger2markup
    sources {
        include 'index.adoc'
    }
    backends = ['html5', 'pdf']
    attributes = [
            doctype    : 'book',
            toc        : 'left',
            toclevels  : '3',
            numbered   : '',
            sectlinks  : '',
            sectanchors: '',
            hardbreaks : '',
            generated  : asciiDocOutputDir
    ]
}

In the logs I get

:convertSwagger2markup
reading from /home/ashwani/project/test/build/swagger/swagger.json
:asciidoctor UP-TO-DATE

BUILD SUCCESSFUL

I am not sure what is wrong in my configuration.
Please have a look.
Thanks,
Ashwani

Will this work with Springfox > 2.7?

I am having trouble getting this to work with the latest version of spring-fox. Has anyone else been successful?