springboot 整合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集成Swagger2

1 创建SpringBoot 项目

2 导入相关依赖

 <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>

配置Swagger （使用默认配置）

启动项目

浏览器中测试

http://localhost:8080/swagger-ui.htm

至此集成结束

自定义配置信息：

package com.swagger.config;

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

import java.util.ArrayList;


/**
 * 开启Swagger2
 *
 * @author kuai
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 配置Sawagger2 的Docket的Bean 实例
     */

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
     //作者信息
        Contact contact = new Contact("蒯厅", "urn:tos", "1941726287@qq.com");
        return new ApiInfo("哟呵的Swagger API",
                "越努力月幸运！",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置扫描接口及开关

.select()
.blud()
//RequestHandlerselectors.配置要扫捕接口的方式
当我没配置 .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
//basePackage:指定要扫描的包
//any():扫赬全部
//none():不扫描
//wi thClassAnnotation;扫描类上的注解，参数是一个注解的反射对象
//withMe thodAnnotation:扫捕方法上的注解
.apis(Reques tHandlerSelectors . basePackage ("com. swagger .controller"))
//paths().过滤什么路径

配置之后：

常用注解

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

      code：数字，例如400

   message：信息，例如"请求参数没填好"

    response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

     @ApiModelProperty：描述一个model的属性

配置分组（方便多用户协同开发项目）

 @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

注解使用在实体类上的作用

可做代码测试（类似Postman)

美化Swagger

导入依赖：

 <!-- swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.4</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>3.0.2</version>
        </dependency>

Swagger 配置

@Configuration
@EnableSwaggerBootstrapUI
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //分组
                .groupName("all")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试SWAGGER_2接口")
                .version("1.0.1")
                .description("项目演示学习")
                .contact(new Contact("哟呵", "https://blog.csdn.net/qq_45834006?spm=1018.2118.3001.5343", "1941726287@qq.com"))
                .termsOfServiceUrl("https://blog.csdn.net/qq_45834006?spm=1018.2118.3001.5343")
                .build();
    }

Controller 层

/**
 * @author kate
 */
@RestController
@Api("这是啥")
public class HahaController {
    @RequestMapping("/haha")
    @ApiOperation("哈哈哈")
    public  String fun(){
        return "hahha";
    }
}

@RestController
@Api("测试环境")
public class TestConteroller{
    @RequestMapping("/test")
    @ApiOperation("测试环境是否可用")
    public String fun(){
        return " web project is ok ！！";
    }


}

启动项目 访问 http://localhost:8080/doc.html 或者 http://localhost:8080/swagger-ui.html