【原】swagger2markup+swagger2+sprin

作者: 曹赫洋 | 来源:发表于2018-01-17 16:17 被阅读1493次

【原】swagger2markup+swagger2+sprin
原原原相机♡☀❤
原滋原味
原滋原味
西原，西原
原原回来了
原起原灭
马原！马原！
原滋原味
《罪原》《福原》

首先我们看一看效果图，高大上有木有啊有木有。

image.png

image.png
主要参考
https://leongfeng.github.io/2017/02/20/springboot-springfox-swagger2markup-spring-restdoc/
https://github.com/Swagger2Markup/spring-swagger2markup-demo
http://swagger2markup.github.io/swagger2markup/1.3.1/

这里笔者主要是参照官网的spring-swagger2markup-demo进行参考搭建的。

接下来我们来说一下是如何搞定的

1.在项目增加一个文件夹docs

直接从spring-swagger2markup-demo里把这个文件夹复制到自己的项目里就可以，复制的时候还有个manual_content1.adoc 和 manual_content2.adoc的文件，这个文件是接口文档的自定义说明部分，我用不到所以就删了，文件删除之后还要把index.adoc里对应的地方也删掉。

image.png

index.adoc 内容如下：

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::{generated}/definitions.adoc[]

2.项目中添加maven依赖和插件

properties部分

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <spring.boot.version>1.5.8.RELEASE</spring.boot.version>
        
        <com.google.guava.version>19.0</com.google.guava.version>
        <springfox.version>2.5.0</springfox.version>
        <!--自定义的pagehelper版本  edit by sunxiaoyue-->
        <pagehelper.version>4.2.1</pagehelper.version>
        <javax.ws.rs-api.version>2.0</javax.ws.rs-api.version>
        <org.apache.poi.version>3.10-beta2</org.apache.poi.version>
        <jsch.version>0.1.46</jsch.version>
        <commons-lang3.verison>3.3.2</commons-lang3.verison>
        <commons-beanutils.version>1.8.3</commons-beanutils.version>
        <javax.mail.version>1.4.1</javax.mail.version>
        <swagger2markup.version>1.2.0</swagger2markup.version>
</properties>

dependency部分

<dependencies>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.6</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${com.google.guava.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.dataformat</groupId>
            <artifactId>jackson-dataformat-smile</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.module</groupId>
            <artifactId>jackson-module-afterburner</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>${springfox.version}</version>
           
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.module</groupId>
            <artifactId>jackson-module-jsonSchema</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.github.robwin</groupId>
            <artifactId>assertj-swagger</artifactId>
            <version>0.2.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
            <scope>test</scope>
        </dependency>

        <!--使用log4j2 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>jcl-over-slf4j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
</dependencies>

maven plugin部分


    <build>
        <plugins>

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <!--docker 插件-->
            <plugin>
                <groupId>com.spotify</groupId>
                <artifactId>docker-maven-plugin</artifactId>
                <version>0.4.13</version>
                <configuration>
                    <forceTags>true</forceTags>
                    <!--<imageName>10.0.0.95:5000/${project.artifactId}:${project.version}</imageName>-->
                    <imageName>10.0.0.95:5000/JAVA_Account-Service:${project.version}</imageName>
                    <dockerDirectory>${project.basedir}/src/main/docker</dockerDirectory>
                    <resources>
                        <resource>
                            <targetPath>/</targetPath>
                            <directory>${project.build.directory}</directory>
                            <include>${project.build.finalName}.jar</include>
                        </resource>
                    </resources>
                </configuration>
            </plugin>

            <!--Swagger2Markup相关插件 begin-->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <systemPropertyVariables>
                        <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
                        <io.springfox.staticdocs.snippetsOutputDir>${swagger.snippetOutput.dir}</io.springfox.staticdocs.snippetsOutputDir>
                    </systemPropertyVariables>
                </configuration>
            </plugin>

            <!-- First, use the swagger2markup plugin to generate asciidoc -->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>${swagger2markup.version}</version>
                <dependencies>
                    <dependency>
                        <groupId>io.github.swagger2markup</groupId>
                        <artifactId>swagger2markup-import-files-ext</artifactId>
                        <version>${swagger2markup.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>io.github.swagger2markup</groupId>
                        <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
                        <version>${swagger2markup.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <swaggerInput>${swagger.input}</swaggerInput>
                    <outputDir>${generated.asciidoc.directory}</outputDir>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

                        <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
                        <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
                        <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
                        <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>

                        <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
                        <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
                    </config>
                </configuration>
                <executions>
                    <execution>
                        <phase>test</phase>
                        <goals>
                            <goal>convertSwagger2markup</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                        <generated>${generated.asciidoc.directory}</generated>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

            <!-- specify the main class for the manifest -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>2.4</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <classpathPrefix>lib/</classpathPrefix>
                            <mainClass>io.github.robwin.swagger2markup.petstore.Application</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>

            <!-- copy dependencies to the lib directory -->
            <plugin>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>copy-dependencies</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.directory}/lib</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <!-- copy the generated documents -->
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>2.7</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>${asciidoctor.html.output.directory}</directory>
                                </resource>
                                <resource>
                                    <directory>${asciidoctor.pdf.output.directory}</directory>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!--Swagger2Markup相关插件 end-->
        </plugins>
    </build>

这里需要做如下几点说明

log4j2的部分，官方的demo中使用的logback，但是我的项目里用的是log4j2，所以这里我有做处理，slf4j换成了log4j2，撰文时，官方的demo里用springfox.version是2.4.0，笔者全部升级为了2.5.0

3.swagger的使用部分

SwaggerConfig代码

package com.weds.account;

import com.google.common.base.Predicates;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.ant;

import com.google.common.base.Predicates;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Arrays;

import static java.util.Arrays.asList;
import static springfox.documentation.builders.PathSelectors.ant;

@EnableSwagger2
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.account.web")).paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("账户微服务接口文档")
                .description("账户微服务接口文档")
                .contact(new Contact("XXX数据", "http://www.weds.com.cn", "caoheyang@weds.com.cn"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

注意：如果你是参照官方文档添加的maven依赖，那这个SwaggerConfig 必须是在单元测试的包模块下，因为官方的依赖里springfox-bean-validators的scope是test，只有在test下才会被成功引入到SwaggerConfig 中。restApi部分采用的是basePackage方式，这样可以忽略比如actuator的rest接口也被拿来生成了接口文档。

3.REST接口以及实体类定义部分

package com.weds.account.web.inter;

import com.weds.framework.core.common.model.PagedResponse;

import com.weds.account.entity.req.*;
import com.weds.account.entity.resp.App_Account_Query_Resp;
import com.weds.framework.core.common.model.JsonResult;

import org.springframework.web.bind.annotation.*;

import static org.springframework.http.MediaType.APPLICATION_JSON_VALUE;

/**
 * 应用账户相关的接口
 * Created by Caoheyang on 2018-01-06.
 */
@RestController
@RequestMapping(value = "/app/account", produces = {APPLICATION_JSON_VALUE})
public interface AppAccountInter {
    /**
     * 新增应用账户接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @param req
     * @return
     */
    @PutMapping(path = "/add")
    public JsonResult add(@RequestBody App_Account_Add_Req req);

    /**
     * 修改应用账户信息接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @param req
     * @return
     */
    @PostMapping(path = "/modify")
    public JsonResult modify(@RequestBody App_Account_Modify_Req req);

    /**
     * 修改应用账户密码接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @param req
     * @return
     */
    @PostMapping(path = "/modify_pass")
    public JsonResult modifyPass(@RequestBody App_Account_Modify_Pass_Req req);

    /**
     * 删除应用账户接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @param app_account 应用账户
     * @return
     */
    @DeleteMapping(path = "/delete/{app_account}")
    public JsonResult delete(@PathVariable("app_account") String app_account);

    /**
     * 查询某个应用账户接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @return
     */
    @PostMapping(path = "/searchone")
    public JsonResult<App_Account_Query_Resp> searchOne();

    /**
     * 查询应用账户列表接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @return
     */
    @PostMapping(path = "/search")
    public JsonResult<PagedResponse<App_Account_Query_Resp>> search();

    /**
     * 应用账户登陆接口
     * Created by Caoheyang on 2018-01-06.
     *
     * @param req
     * @return
     */
    @PostMapping(path = "/login")
    public JsonResult<App_Account_Query_Resp> login(@RequestBody App_Account_Login_Req req);
}

package com.weds.account.web;

import com.weds.account.entity.req.*;
import com.weds.account.entity.resp.App_Account_Query_Resp;
import com.weds.account.web.inter.AppAccountInter;
import com.weds.framework.core.common.model.JsonResult;
import com.weds.framework.core.common.model.PagedResponse;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

/**
 * 应用账户相关服务的Controller Created by Caoheyang on 2018-01-06.
 */
@RestController
@Api(value = "应用账户管理", description = "应用账户相关的接口")
public class AppAccountController implements AppAccountInter {

    @ApiOperation(value = "新增应用账户接口", notes = "新增应用账户接口")
    @Override
    public JsonResult add(
            @ApiParam(value = "入参", required = true) @RequestBody App_Account_Add_Req req) {
        return null;
    }

    @ApiOperation(value = "修改应用账户信息接口", notes = "修改应用账户信息接口")
    @Override
    public JsonResult modify(
            @ApiParam(value = "入参", required = true) @RequestBody App_Account_Modify_Req req) {
        return null;
    }

    @ApiOperation(value = "修改应用账户密码接口", notes = "修改应用账户密码接口")
    @Override
    public JsonResult modifyPass(
            @ApiParam(value = "入参", required = true) @RequestBody App_Account_Modify_Pass_Req req) {
        return null;
    }

    @ApiOperation(value = "删除应用账户接口", notes = "删除应用账户接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "app_account", value = "应用账户", required = true, paramType = "path", dataType = "string")})
    @Override
    public JsonResult delete(@PathVariable("app_account") String app_account) {
        return null;
    }

    @ApiOperation(value = "查询某个应用账户接口", notes = "查询某个应用账户接口")
    @Override
    public  JsonResult<App_Account_Query_Resp>  searchOne() {
        return null;
    }

    @ApiOperation(value = "查询应用账户列表接口", notes = "查询应用账户列表接口")
    @Override
    public JsonResult<PagedResponse<App_Account_Query_Resp>>  search() {
        return null;
    }

    @ApiOperation(value = "应用账户登陆接口", notes = "应用账户登陆接口")
    @Override
    public  JsonResult<App_Account_Query_Resp>  login(
            @ApiParam(value = "入参", required = true) @RequestBody App_Account_Login_Req req) {
        return null;
    }
}

package com.weds.account.entity.req;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

import java.io.Serializable;
import java.util.Map;

/**
 * 新增应用账户接口 入参
 * Created by Caoheyang on 2018-01-08.
 */
@JsonIgnoreProperties(ignoreUnknown = true)
public class App_Account_Add_Req implements Serializable{

    //应用账户,用一个应用下的应用账户具有唯一性
    @ApiModelProperty(required = true, dataType = "string", example = "admin",
            value = "应用账户,用一个应用下的应用账户具有唯一性")
    @Getter
    @Setter
    private String app_account;

    //应用账户标签,json格式，根据平台入驻时与账户微服务预定义的标签，由平台应用自行存储
    @ApiModelProperty(required = true, dataType = "string", example = "{\"class\":\"03\",\"type\":\"teacher\"}",
            value = "应用账户标签,json格式，根据平台入驻时与账户微服务预定义的标签，由平台应用自行存储")
    @Getter
    @Setter
    private Map<String, String> label;

    //应用账户密码 DES加密之后的密文
    @ApiModelProperty(required = true, dataType = "string", example = "FFWERWRFGP34DFWE",
            value = "应用账户密码，DES加密之后的密文")
    @Getter
    @Setter
    private String password;

    //角色编码,以”;角色码1;角色码2;”形式存储
    @ApiModelProperty(required = false, dataType = "string", example = ";0011;0032;",
            value = "角色编码,以”;角色码1;角色码2;”形式存储")
    @Getter
    @Setter
    private String role_nos;

    //添加人 默认值为system
    @ApiModelProperty(required = false, dataType = "string", example = "system",
            value = "添加人 默认值为system")
    @Getter
    @Setter
    private String inserted_by;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注1",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_1;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注2",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_2;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注3",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_3;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注4",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_4;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注5",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_5;
}

package com.weds.account.entity.resp;

import com.weds.account.entity.App_Account_Role;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

import javax.management.relation.Role;
import java.io.Serializable;
import java.util.List;
import java.util.Map;

/**
 * 查询某个应用账户接口 返回数据结构
 * Created by Caoheyang on 2018-01-09.
 */
public class App_Account_Query_Resp implements Serializable {
    //基础账户编号
    @ApiModelProperty(required = true, dataType = "int", example = "123",
            value = "基础账户编号")
    @Getter
    @Setter
    private int basic_acc_no;

    //应用账户
    @ApiModelProperty(required = true, dataType = "string", example = "admin",
            value = "应用账户")
    @Getter
    @Setter
    private String app_account;

    //身份证号码
    @ApiModelProperty(required = false, dataType = "string", example = "370685199010111215",
            value = "身份证号码")
    @Getter
    @Setter
    private String id_card;

    //真实姓名
    @ApiModelProperty(required = true, dataType = "string", example = "张三",
            value = "真实姓名")
    @Getter
    @Setter
    private String name;

    //性别 男 女
    @ApiModelProperty(required = true, dataType = "int", example = "男",
            value = "性别")
    @Getter
    @Setter
    private String sex;

    //手机号码1
    @ApiModelProperty(required = false, dataType = "string", example = "18888888888",
            value = "手机号码1")
    @Getter
    @Setter
    private String mobilephone;

    //手机号码2
    @ApiModelProperty(required = false, dataType = "string", example = "18888888888",
            value = "手机号码2")
    @Getter
    @Setter
    private String mobilephone2;

    //固话
    @ApiModelProperty(required = false, dataType = "string", example = "0535-80888888",
            value = "固话")
    @Getter
    @Setter
    private String telephone;

    //邮箱1
    @ApiModelProperty(required = false, dataType = "string", example = "weds@weds.com.cn",
            value = "邮箱1")
    @Getter
    @Setter
    private String email;

    //邮箱2
    @ApiModelProperty(required = false, dataType = "string", example = "weds1@weds.com.cn",
            value = "邮箱2")
    @Getter
    @Setter
    private String email2;

    //应用账户状态
    @ApiModelProperty(required = true, dataType = "int", example = "0",
            value = "应用账户状态")
    @Getter
    @Setter
    private int app_account_status;

    //标签  JSON数据体
    @ApiModelProperty(required = true, dataType = "string", example = "{\"class\":\"03\",\"type\":\"teacher\"}",
            value = "应用账户标签,json格式，根据平台入驻时与账户微服务预定义的标签，由平台应用自行存储")
    @Getter
    @Setter
    private Map<String, String> label;

    //角色,信息 JONS 数组
    @ApiModelProperty(required = true, dataType = "string", example = "admin",
            value = "角色数组")
    @Getter
    @Setter
    private List<App_Account_Role> role_nos;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注1",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_1;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注2",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_2;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注3",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_3;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注4",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_4;

    //备用标注,应用自定义存储，自行解析
    @ApiModelProperty(required = false, dataType = "string", example = "备注5",
            value = "备用标注,应用自定义存储，自行解析")
    @Getter
    @Setter
    private String column_5;
}

注意：
1.我这里用了lombok所以没有get，set方法，只有 @Getter和@Setter注解
2.在与swagger2markup的集成中发现，必须用@ApiParam注解，而且实体上不可以加ApiModel否则swagger2markup部分的生成会失败，无法映射接口的入参和返回值部分。
3.在swagger2中response部分不需要写，关于泛型部分也会自己直接映射的。

@ApiImplicitParam在 @RequestBody联合使用的过程中，在swaggerui下没问题，但是在swagger2markup下是有问题的，无法生成swagger2markup文档，需要注意！

4.使用swagger2markup生成文档

1.需要新建一个Swagger2MarkupTest类，代码如下

package com.weds.account;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;

import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
@SpringBootTest(classes = {AccountServiceApplication.class, SwaggerConfig.class})
@AutoConfigureMockMvc
public class Swagger2MarkupTest {

    @Autowired
    private MockMvc mockMvc;

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

        String outputDir = System.getProperty("io.springfox.staticdocs.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);
        }
    }
}

2.执行maven 的clean命令然后执行test命令

image.png
插件会自动生成接口文件到target下，文件是adoc格式的。
由于插件会提现把接口文档生成为adoc文件，放到target下，所以对项目的实际运行速度毫无影响。
这时如果执行spring boot的run 命令，请求http://localhost:1234/docs/index.html发现是500的错误，但是如果把执行maven的package命令，然后在执行spring boot的run 命令或者 java -jar 项目.jar 把项目跑起来，然后在访问 http://localhost:1234/docs/index.html 就ok了，并且 http://localhost:1234/swagger-ui.html 也是ok的。

github开源代码：https://github.com/caoheyang/swagger2markupdemo
oschina开源代码：https://gitee.com/caoheyang/swagger2markupdemo
请注意代码中还有很多的依赖是自己封装的，请参照博客查找swagger2markup部分即可。

【原】swagger2markup+swagger2+sprin
首先我们看一看效果图，高大上有木有啊有木有。这里笔者主要是参照官网的spring-swagger2markup-...
原原原相机♡☀❤
原滋原味
原滋原味酒失去了原有的芳香衣失去了原有的作用节失去了原有的味道年失去了原有的气息一切的一切都发生了改变 ...
原滋原味
有没有这样一种感情，经历人情世故的染指，依然原滋原味。 ――题记破晓前的清冽与隐落后的...
西原，西原
那一天看起来与平日里的每一天没有什么不同。阳光照在草原上，天高，云淡，风清，青草肆意地生长。她风华正好，明眸...
原原回来了
昨晚睡得晚了一点，早上醒的时候，大概九点多，一直恍恍惚惚。随手翻开手机，看到原原的留言，才记起今天是她回来的日子。...
原起原灭
生活好似一个圆，从这个点出发，兜兜转转，最终都要回到这个点。可能我们一直在回到原点，可是起点、终点、原点；原点、起...
马原！马原！
绪论 1、马克思主义三个组成部分：马克思主义哲学，马克思主义政治经济学，科学社会主义 2、中共和中国社会主义事业指...
原滋原味
＂咋这么快接起来了＂按下接听键清脆的声音伴着甜甜的笑声，顺着电话线的听筒传过来，外人通过声音绝对听不出来亲家姐姐的...
《罪原》《福原》
罪原来自于不敢去打破阻挡真实的屏障福原来原于海纳百川的完善积累看都是是相同的树叶，但却没有完全相同的两片树叶，...