Swagger简介

1、认识Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

1. 接口的文档在线自动生成。

2. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

springboot整合Swagger

①添加依赖

<!-- swagger2借口测试-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<!-- swagger2-UI-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

② 新建一个类配置Swagger

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


/**
 * Swagger2的接口配置
 * 
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 详细定制
                .apiInfo(apiInfo())
                .select()
                // 指定当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.bettn"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                .title("标题：bettn系统接口文档")
                .description("描述：用于测试接口")
                .contact(new Contact("hzhh123", null, null))
                .version("0.0.1")
                .build();
    }
}

③开启扫描包

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages={"com"})  //swagger扫描基类包
public class BettnAdminApplication {

    public static void main(String[] args) {
        SpringApplication.run(BettnAdminApplication.class, args);
    }

}

④写一个类方便访问

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import io.swagger.annotations.Api;
@Api(value = "swagger访问页面",description = "swagger访问页面")
@Controller
public class SwaggerController{
    @RequestMapping("/api/swagger")
    public String toSwaggerUI(){
        return "redirect:/swagger-ui.html";
    }
}

Swagger的注解说明

@ApiParam(name=参数,value=参数说明,required=false|true)

注解写在参数的最左边，且参数需要使用@RequestBody、@RequestParam、@PathVariable参数修饰才起作用

@Api(value = 接口类标志,description = 接口类说明)

一般放在类上

@ApiOperation(value = 方法作用名,notes = 方法描述)

修饰方法，放在方法上

具体参考：https://blog.csdn.net/sanyaoxu_2/article/details/80555328

swagger-ui升级swagger-bootstrap-ui界面好看到起飞

如果项目已经集成了swagger，只需要在pom.xml添加，如果你的项目没有集成swagger，自行百度或看最下方的链接

swagger-bootstrap-ui是Swagger的前端UI实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好一点儿....

swagger-bootstrap-ui 只是Swagger的UI实现,并不是替换Swagger功能,所以后端模块依然是依赖Swagger的,需要配合Swagger的注解达到效果

添加依赖

<!--swagger-bootstrap-ui  -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

最终的依赖

<!-- swagger2借口测试-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<!-- swagger2-UI-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!--swagger-bootstrap-ui  -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

访问

如 http://localhost:8080/doc.html

swagger-bootstrap-ui介绍

https://www.oschina.net/p/swagger-bootstrap-ui

码云：https://gitee.com/xiaoym/swagger-bootstrap-ui

GITHUB:https://github.com/xiaoymin/Swagger-Bootstrap-UI

在线体验：http://swagger-bootstrap-ui.xiaominfo.com/doc.html