Swagger2Markup

https://swagger2markup.github.io/swagger2markup/1.3.3/
Admin
Swagger2Markup is a tool that converts Swagger JSON or YAML API specifications into AsciiDoc,...
Tokens:13,853
Snippets:121
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Petstore Sample Content File Structure

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

An example demonstrating how to organize content files for different extensions using distinct content paths. Files are applied based on their path and naming convention, with multiple files for the same operation sorted by natural order.

```text
overview/document-before-intro.adoc __**(1)**
paths/document-before-intro.adoc __**(2)**
paths/updatePet/operation-begin-description.adoc
paths/updatePet/operation-end-example1.adoc
paths/updatePet/operation-end-example2.adoc __**(3)**
definitions/Pet/definition-begin-description.adoc
```

--------------------------------

### Inline schema with title items

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

An example of an inline schema definition using JSON Schema title items to provide explicit naming for intermediate references.

```yaml
  InlineTitlePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        **title: CategoryModel**
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          **title: TagModel**
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
```

--------------------------------

### Spring RestDocs test for /pets endpoint

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

JUnit test using Spring RestDocs to test the /pets endpoint and write example files into the build/snippets folder. The document name "addPet" matches the operationId from the Swagger example.

```java
@Rule
public final RestDocumentation restDocumentation = new RestDocumentation("build/snippets");

@Test
public void addAPetToTheStore() throws Exception {
  this.mockMvc.perform(post("/pets/").content(createPet())
    .contentType(MediaType.APPLICATION_JSON))
    .andDo(document("addPet", preprocessResponse(prettyPrint())))
    .andExpect(status().isOk());
}
```

--------------------------------

### Inline schema without title items

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

An example of an inline schema definition in Swagger where no title items are provided, leading to default naming behavior.

```yaml
  InlinePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
```

--------------------------------

### Gradle dependency for dynamic file import extension

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Add the dynamic file import extension to your classpath using Gradle. The extension searches for markup files in configurable paths and appends them at supported document positions. Files must follow a naming convention that starts with the position and ends with the markup extension (e.g., adoc or md).

```groovy
repositories {
    compile()
}

compile "io.github.swagger2markup:swagger2markup-import-files-ext:1.3.4-SNAPSHOT"
```

--------------------------------

### Swagger operationId example for /pets

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Swagger definition for the /pets endpoint with an explicit operationId. The operationId is used to locate the corresponding Spring RestDocs snippet files; it is case-sensitive and recommended to set it.

```yaml
paths:
  /pets:
    post:
      summary: Add a new pet to the store
      operationId: addPet
      ...
```

--------------------------------

### Build Demo Project

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Command to clean and build the demo project.

```bash
gradlew clean build
```

--------------------------------

### Show CLI help

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Displays the help information for the convert command.

```bash
java -jar swagger2markup-cli-1.3.3.jar help convert
```

```text
NAME
        swagger2markup convert - Converts a Swagger JSON or YAML file into
        Markup documents.

SYNOPSIS
        swagger2markup convert [(-c <configFile> | --config <configFile>)]
                [(-d <outputDir> | --outputDir <outputDir>)]
                [(-f <outputFile> | --outputFile <outputFile>)]
                (-i <swaggerInput> | --swaggerInput <swaggerInput>)

OPTIONS
        -c <configFile>, --config <configFile>
            Config file.

        -d <outputDir>, --outputDir <outputDir>
            Output directory. Converts the Swagger specification into multiple
            files.

        -f <outputFile>, --outputFile <outputFile>
            Output file. Converts the Swagger specification into one file.

        -h, --help
            Display help information

        -i <swaggerInput>, --swaggerInput <swaggerInput>
            Swagger input. Can either be a URL or a file path.
```

--------------------------------

### Run Demo Application

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Command to execute the generated Spring Boot JAR file.

```bash
java -jar build/libs/spring-swagger2markup-demo-{project-version}.jar
```

--------------------------------

### Configure from a Properties file

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Loads configuration properties from a file to initialize the Swagger2MarkupConfig.

```java
Properties properties = new Properties();
properties.load(DocumentationTest.class.getResourceAsStream("/config/config.properties")); __**(1)**

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(properties) __**(2)**
        .build();

Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
        .withConfig(config)
        .build();
```

--------------------------------

### Execute convertSwagger2markup task

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Run the plugin task using the Gradle wrapper.

```bash
gradlew convertSwagger2markup
```

--------------------------------

### Configure and run CLI

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Customizes Swagger2Markup properties using a config.properties file and invokes the CLI with the configuration.

```properties
swagger2markup.markupLanguage=MARKDOWN
swagger2markup.outputLanguage=DE
```

```bash
java -jar swagger2markup-cli-1.3.3.jar convert -i /path/to/swagger_petstore.yaml -o /tmp -c /path/to/config.properties
```

--------------------------------

### Create a Custom Extension Class

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Implement a custom extension by extending one of the provided SPI classes, such as DefinitionsDocumentExtension. The init method handles one-time configuration, while the apply method is invoked per document element.

```java
public class MyExtension extends DefinitionsDocumentExtension {

    private static final String EXTENSION_ID = "myExtension";
    private String extensionProperty;

    @Override
    public void init(Swagger2MarkupConverter.Context globalContext) {
        // init is executed once
        Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties(); __**(1)**
        extensionProperty = extensionProperties.getRequiredString(EXTENSION_ID + ".propertyName");
        Swagger model = globalContext.getSwagger();
    }

    @Override
    public void apply(Context context) {
        MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder(); __**(2)**
        Position position = context.getPosition(); __**(3)**
        String definitionName = context.getDefinitionName().get();
        Model definitionModel = context.getModel().get();

        if (position.equals(Position.DEFINITION_END)) {
            markupBuilder.sectionTitleLevel1(definitionName) __**(4)**
                    .paragraph(definitionModel.getDescription())
                    .importMarkup(new StringReader("*Markup*"), MarkupLanguage.ASCIIDOC);
        }

        // apply is executed per definition
    }
}
```

--------------------------------

### Generate Documentation Only

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Command to generate HTML and PDF documentation using the asciidoctor task.

```bash
gradlew clean asciidoctor
```

--------------------------------

### Run Swagger2Markup Maven Goal

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Execute the conversion task using the provided Maven goal.

```bash
mvn swagger2markup:convertSwagger2markup
```

--------------------------------

### Configure convertSwagger2markup task

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Customize the conversion process by defining the input file, output directory, and configuration properties within the task block.

```groovy
convertSwagger2markup {
    swaggerInput file("src/docs/swagger/swagger_petstore.yaml").getAbsolutePath()
    outputDir file("${buildDir}/asciidoc")
    config = ['swagger2markup.markupLanguage' : 'ASCIIDOC',
              'swagger2markup.pathsGroupedBy' : 'TAGS']
}
```

--------------------------------

### Configure from a Map

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Uses a Map to define Swagger2MarkupProperties for the configuration builder.

```java
Map<String, String> configMap = new HashMap<>(); __**(1)**
configMap.put(Swagger2MarkupProperties.MARKUP_LANGUAGE, MarkupLanguage.MARKDOWN.toString());
configMap.put(Swagger2MarkupProperties.OUTPUT_LANGUAGE, Language.DE.toString());
configMap.put(Swagger2MarkupProperties.PATHS_GROUPED_BY, GroupBy.TAGS.toString());

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(configMap) __**(2)**
        .build();

Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
        .withConfig(config)
        .build();
```

--------------------------------

### Configure Swagger2Markup with Apache Commons Configuration

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Create an Apache Commons Configuration object and use it to build a Swagger2MarkupConfig instance for the converter.

```java
Configurations configs = new Configurations();
Configuration configuration = configs.properties("config.properties"); __**(1)**

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(configuration) __**(2)**
        .build();

Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
        .withConfig(config)
        .build();
```

--------------------------------

### Gradle Release Configuration

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Add the JCenter repository and the Swagger2Markup dependency to your build.gradle file.

```groovy
repositories {
    jCenter()
}

compile "io.github.swagger2markup:swagger2markup:1.3.3"
```

--------------------------------

### Convert local Swagger file to folder

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a local Swagger file into multiple documentation files within a specified output directory.

```java
Path localSwaggerFile = Paths.get("/path/to/swagger.yaml");
Path outputDirectory = Paths.get("build/asciidoc");

Swagger2MarkupConverter.from(localSwaggerFile) __**(1)**
        .build() __**(2)**
        .toFolder(outputDirectory); __**(3)**
```

--------------------------------

### Convert Swagger Spec with Docker

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Command to run the Swagger2Markup container to convert a local Swagger file.

```bash
docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger.yaml -f /opt/swagger -c /opt/config.properties
```

--------------------------------

### Maven Release Configuration

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Include the JCenter repository and the Swagger2Markup dependency in your pom.xml file.

```xml
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>
```

--------------------------------

### Configure Swagger2Markup Plugin

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Customize the plugin behavior by defining input paths, output directories, and configuration properties within the configuration block.

```xml
<build>
    <plugins>
      <plugin>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup-maven-plugin</artifactId>
        <version>1.3.3</version>
        <configuration>
          <swaggerInput>${project.basedir}/src/docs/swagger/swagger_petstore.yaml</swaggerInput>
          <outputDir>${project.build.directory}/asciidoc</outputDir>
          <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
          </config>
        </configuration>
      </plugin>
    </plugins>
</build>
```

--------------------------------

### Gradle Snapshot Configuration

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Configure the snapshot repository URL in your build.gradle file to access development builds.

```groovy
repositories {
   maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}
```

--------------------------------

### Maven Snapshot Configuration

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Configure the snapshot repository URL in your pom.xml file to access development builds.

```xml
<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </repository>
</repositories>
```

--------------------------------

### Convert Swagger file to a single file

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a local Swagger specification into a single documentation file.

```java
Path localSwaggerFile = Paths.get("/path/to/swagger.yaml");
Path outputFile = Paths.get("build/swagger.adoc");

Swagger2MarkupConverter.from(localSwaggerFile)
        .build()
        .toFile(outputFile);
```

--------------------------------

### Convert Swagger file to folder

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a Swagger file into multiple Markup documents within a specified directory.

```bash
java -jar swagger2markup-cli-1.3.3.jar convert -i /path/to/swagger_petstore.yaml -d /tmp/asiidoc
```

--------------------------------

### Add swagger2markup-import-schemas-ext dependency

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Adds the swagger2markup-import-schemas-ext dependency to a Gradle build. The extension searches for schema files in a configurable path and appends their content at the end of a definition section.

```groovy
repositories {
    jCenter()
}

compile "io.github.swagger2markup:swagger2markup-import-schemas-ext:1.3.4-SNAPSHOT"
```

--------------------------------

### Convert remote Swagger file to folder

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a remote Swagger specification accessible via HTTP into documentation files within a specified output directory.

```java
URL remoteSwaggerFile = new URL("http://petstore.swagger.io/v2/swagger.json");
Path outputDirectory = Paths.get("build/asciidoc");

Swagger2MarkupConverter.from(remoteSwaggerFile) __**(1)**
        .build() __**(2)**
        .toFolder(outputDirectory); __**(3)**
```

--------------------------------

### Convert Swagger file to single file

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a local Swagger file into a single Markup document. The input file path must not have a file extension.

```bash
java -jar swagger2markup-cli-1.3.3.jar convert -i /path/to/swagger_petstore.yaml -f /tmp/asiidoc/swagger
```

--------------------------------

### Convert Swagger to AsciiDoc with MockMvc

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Uses Spring MVC Test and Swagger2MarkupResultHandler to capture the Swagger JSON response and save it to a directory.

```java
@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
public class Swagger2MarkupTest {

    @Autowired
    private WebApplicationContext context;

    private MockMvc mockMvc;

    @Before
    public void setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();
    }

    @Test
    public void convertSwaggerToAsciiDoc() throws Exception {
        this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler
                    .outputDirectory("src/docs/asciidoc/generated").build())
                .andExpect(status().isOk());
    }
}
```

--------------------------------

### Convert remote Swagger file

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a remote Swagger specification accessible via HTTP.

```bash
java -jar swagger2markup-cli-1.3.3.jar convert -i "http://petstore.swagger.io/v2/swagger.json" -d /tmp
```

--------------------------------

### Add Swagger2Markup Maven Plugin to POM

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Include the plugin repositories and the swagger2markup-maven-plugin dependency in your project's pom.xml file.

```xml
<pluginRepositories>
    <pluginRepository>
        <id>jcenter-snapshots</id>
        <name>jcenter</name>
        <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </pluginRepository>
    <pluginRepository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </pluginRepository>
</pluginRepositories>

<build>
    <plugins>
      <plugin>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup-maven-plugin</artifactId>
        <version>1.3.3</version>
      </plugin>
    </plugins>
</build>
```

--------------------------------

### Add Swagger2Markup Gradle Plugin to buildscript

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Include the plugin in your Gradle build file by adding the dependency to the buildscript block and applying the plugin.

```groovy
buildscript {
    repositories {
        jcenter()
        maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
    }

    dependencies {
        classpath 'io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.3'
    }
}

apply plugin: 'io.github.swagger2markup'
```

--------------------------------

### Add swagger2markup-spring-restdocs-ext dependency

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Adds the swagger2markup-spring-restdocs-ext dependency to a Gradle build. The extension includes generated CURL request, HTTP request, and HTTP response snippets from spring-restdocs into the generated Markup documents.

```groovy
repositories {
    jCenter()
}

compile "io.github.swagger2markup:swagger2markup-spring-restdocs-ext:1.3.4-SNAPSHOT"
```

--------------------------------

### Convert Swagger file to a String

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Converts a local Swagger specification into a String representation.

```java
Path localSwaggerFile = Paths.get("/path/to/swagger.yaml");

String documentation = Swagger2MarkupConverter.from(localSwaggerFile)
        .build()
        .toString();
```

--------------------------------

### Configure Swagger2MarkupConverter with Builder

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Uses the Swagger2MarkupConfigBuilder to define custom properties for the converter using a fluent API.

```java
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() __**(1)**
        .withMarkupLanguage(MarkupLanguage.MARKDOWN) __**(2)**
        .withOutputLanguage(Language.DE) __**(3)**
        .withPathsGroupedBy(GroupBy.TAGS) __**(4)**
        .build(); __**(5)**

Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
        .withConfig(config) __**(6)**
        .build();
```

--------------------------------

### Pull Swagger2Markup Docker Image

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Command to pull the official Swagger2Markup Docker image from DockerHub.

```bash
docker pull swagger2markup/swagger2markup
```

--------------------------------

### Convert Remote Swagger to AsciiDoc in Spring Test

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Uses Swagger2MarkupConverter to fetch a remote Swagger endpoint and save it to a local folder during integration tests.

```java
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
@WebIntegrationTest
public class Swagger2MarkupTest {

    @Test
    public void convertRemoteSwaggerToAsciiDoc() {
        // Remote Swagger source
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")).build()
            .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }
}
```

--------------------------------

### Register an Extension Manually

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Use the Swagger2MarkupExtensionRegistryBuilder to register custom extensions and apply them to the Swagger2MarkupConverter.

```java
Swagger2MarkupExtensionRegistry registry = new Swagger2MarkupExtensionRegistryBuilder() __**(1)**
        .withDefinitionsDocumentExtension(new MyExtension()) __**(2)**
        .build(); __**(3)**

Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
        .withExtensionRegistry(registry) __**(4)**
        .build();
```

--------------------------------

### Custom SwaggerModelExtension to modify Swagger model

Source: https://swagger2markup.github.io/swagger2markup/1.3.3

Use this extension to modify the Swagger model before Swagger2Markup processes it. You can change any Swagger model property, such as host or basePath, and even remove elements like paths. The numbered comments (1) and (2) highlight where property changes and element removal occur.

```java
public class MySwaggerModelExtension extends SwaggerModelExtension {

    public void apply(Swagger swagger) {
        swagger.setHost("newHostName"); __**(1)**
        swagger.basePath("newBasePath");

        Map<String, Path> paths = swagger.getPaths(); __**(2)**
        paths.remove("/remove");
        swagger.setPaths(paths);
    }
}
```
Tokens:
Raw