swagger2 在springmvc下的使用

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/qq_24615069/article/details/82145523

目录

一、swagger2 生成api文档

1.导入依赖

2.配置swagger

3.使用

4.访问

二、swagger生成离线PDF、HTML文档

1.导入依赖

2.配置asciidoc

3.配置swagger.json

4.运行maven test生成swagger离线文档

5.建议用html，pdf版可能显示不全

---

 

---

一、swagger2 生成api文档

1.导入依赖

        <!-- Swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger-ui.version}</version>
        </dependency>

2.配置swagger

import com.google.common.collect.Sets;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * <p>
 * 说明:swagger配置，自动生成api文档
 * </p>
 *
 * @author lwd
 * @date 2018/8/16
 */
@Configuration
@EnableWebMvc//springmvc必须加上
@EnableSwagger2
public class Swagger2Config {

    private static final Logger log = LoggerFactory.getLogger(Swagger2Config.class);

    /**
     * <p>
     * 说明:创建
     * </p>
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .produces(Sets.newHashSet("application/json"))
                .consumes(Sets.newHashSet("application/json"))
                .protocols(Sets.newHashSet("http"))
                .apiInfo(apiInfo()).select()
                //扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * <p>
     * 说明:信息
     * </p>
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX Api Documentation")
                .description("xxx API接口文档")
                .contact(new Contact("XXX", "http://www.xxx.com", "[email protected]"))
                .version("1.0.0")
                .build();
    }
}

3.使用

①注解说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

②model里

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户对象")
public class TUser {
    @ApiModelProperty(value = "用户id", hidden = true)
    private Long id;
    @ApiModelProperty(value = "用户名", required = true)
    private String nickname;
    @ApiModelProperty(value = "真实姓名", required = true)
    private String realname;
    @ApiModelProperty(value = "密码", hidden = true)
    private String password;
    @ApiModelProperty(value = "证件类型", required = true)
    private String certificateType;
    @ApiModelProperty(value = "证件号", required = true)
    private String certificateCode;
    @ApiModelProperty(value = "手机号", required = true)
    private String phone;
    @ApiModelProperty(value = "办公电话")
    private String officePhone;
    @ApiModelProperty(value = "角色id", required = true)
    private Long roleId;
    @ApiModelProperty(value = "所在机构id", required = true)
    private Long organisationId;
    @ApiModelProperty(value = "备注")
    private String notes;
    @ApiModelProperty(value = "状态：1启用，-1停用", hidden = true)
    private String state;
    @ApiModelProperty(hidden = true)
    private String isDelete;
    @ApiModelProperty(hidden = true)
    private String deleteTime;
    @ApiModelProperty(hidden = true)
    private String updateTime;


    //set get...
}

③controller层使用，简单展示

@Api(description = "用户操作类")
@Validated
@RestController
@RequestMapping(value = "/pobc/sys/user")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "导出用户")
    @ControllerLogAnnotation(description = "用户管理：导出用户")
    @PostMapping(value = "/export")
    public Result<Object> exportExcel() {
        String filepath = userService.exportExcel();
        return new ResultUtil<>().setData(filepath, "导出成功");
    }

    @ApiOperation(value = "获取证件")
    @PostMapping(value = "/getCertificate")
    public Result<Object> getCertificate() {
        List<TCertificate> certificate = userService.getCertificate();
        return new ResultUtil<>().setData(certificate);
    }

    @ApiOperation(value = "模糊+分页查询用户")
    @ControllerLogAnnotation(description = "用户管理：模糊+分页查询用户")
    @PostMapping(value = "/getByFuzzy")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "organisationId", value = "机构id", paramType = "query", dataType = "Long"),
            @ApiImplicitParam(name = "roleId", value = "角色id", paramType = "query", dataType = "Long"),
            @ApiImplicitParam(name = "param", value = "登录名或姓名", paramType = "query", dataType = "String"),
            @ApiImplicitParam(paramType = "query", dataType = "Integer", name = "pageSize", value = "每页条数"),
            @ApiImplicitParam(paramType = "query", dataType = "Integer", name = "pageNumber", value = "第几页")
    })
    public Result<Object> getUserInfo(@RequestParam Long organisationId, @RequestParam Long roleId, @RequestParam String param,
                                      @RequestParam Integer pageSize,
                                      @RequestParam Integer pageNumber) {
        Map<String, Object> map = userService.getUserByUserFuzzy(organisationId, roleId, param, pageSize, pageNumber);
        return new ResultUtil<>().setData(map);
    }

 

4.访问

运行项目之后，访问http://localhost:端口号/swagger-ui.html

二、swagger生成离线PDF、HTML文档

1.导入依赖

只贴入了swagger的

    <repositories>
        <!-- 导入仓库 -->
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </repository>
    </repositories>

    <!-- 集中定义管理依赖版本号 -->
    <properties>
        <!--swagger2 api离线文档开始-->
        <java.version>1.8</java.version>
        <swagger2markup.version>1.2.0</swagger2markup.version>
        <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
        <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
        <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
        <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
        <!--swagger2 api离线文档结束-->
    </properties>
    <build>
        <plugins>
            <!-- 资源文件拷贝插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.0.2</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <!-- Java编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.6.2</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <!-- 配置Tomcat插件 -->
            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat7-maven-plugin</artifactId>
                <version>2.2</version>
                <configuration>
                    <path>/</path>
                    <port>9099</port>
                    <uriEncoding>UTF-8</uriEncoding>
                </configuration>
            </plugin>

            <!-- 以下用于生成adoc文件的配置 开始 -->
            <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>
            <!-- 以下配置用于生成html和pdf -->
            <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.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <generated>${generated.asciidoc.directory}</generated>
                    </attributes>
                </configuration>
                <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>
            <!--以上用于生成adoc文件的配置 开始-->
        </plugins>
        <resources>
            <resource>
                <directory>src/main/java</directory>
                <includes>
                    <include>**/*.xml</include>
                </includes>
                <filtering>true</filtering>
            </resource>
            <resource>
                <directory>src/main/resources</directory>
                <includes>
                    <include>**/*.xml</include>
                    <include>**/*.properties</include>
                </includes>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>

2.配置asciidoc

用于生成离线文档的

index.adoc内容为

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

3.配置swagger.json

想要生成离线文档，需先有在线文档json文件

①启动项目

tomcat maven插件已经配置好，使用 tomcat7:run 跑起来

②访问swagger在线api文档（访问json版）

http://localhost:9099/v2/api-docs

③创建swagger.json

swagger.json内容为刚才http://localhost:9099/v2/api-docs的内容，直接复制粘贴

4.运行maven test生成swagger离线文档

5.建议用html，pdf版可能显示不全