Swagger概述

Swagger概述

概述

• 号称世界上最流行的Api框架：
• RestFul Api 文档在线自动生成工具 ==> Api文档与Api定义同步更新
• 直接运行，可以在线测试Api接口
• 支持多种语言：（Java，Php……）

使用

在项目中使用Swagger 需要 Springbox

• swagger2
• ui

SpringBoot 集成 Swagger

1. 新建一个SpringBoot - web 工程
2. 导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

3. 编写一个hello world项目

package com.dxy.swagger.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello world";
    }
}

4. 配置Swagger ==> SwaggerConfig编写配置类

package com.dxy.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration  //表示这是一个配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {

}

5. 测试运行，访问：http://localhost:8080/swagger-ui.html

配置Swagger 信息

• Swagger的bean实例 Docket （配置基本信息）

package com.dxy.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;

@Configuration  //表示这是一个配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
    Contact contact = new Contact("名字", "http://www.baidu.com", "958023205@qq.com");

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

    private ApiInfo apiInfo() {
        return new ApiInfo("Swagger 学习文档", "Swagger 学习文档 描述", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

Swagger配置扫描接口

• 配置扫描接口 Docket 以及 配置是否启动Swagger2

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .enable(true)   // 配置是否启动Swagger2
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dxy.swagger"))
        //.paths(PathSelectors.ant("/filter/**"))  // 过滤的路径
        .build();
}

• 我只希望我的Swagger在生产环境中使用，在发布的时候不使用？

package com.dxy.swagger.config;

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

import javax.xml.stream.FactoryConfigurationError;
import java.util.ArrayList;

@Configuration  //表示这是一个配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
    Contact contact = new Contact("名字", "http://www.baidu.com", "958023205@qq.com");

    @Bean
    public Docket docket(Environment environment) {
        // 设置要显示的 Swagger 环境
        Profiles profiles = Profiles.of("dev");
        // 通过 environment.acceptsProfiles 判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(flag)   // 配置是否启动Swagger2
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dxy.swagger.controller"))
                //.paths(PathSelectors.ant("/filter/**"))  // 过滤的路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfo("Swagger 学习文档", "Swagger 学习文档 描述", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

1. 配置开发环境

2. 配置上线环境

Swagger配置Api文档分组

• 需要多个组，多个Docket实例即可

@Bean
public Docket docketA() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");	// 组名
}
@Bean
public Docket docketB() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");	// 组名
}

请求数据

实体类配置

package com.dxy.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

接受参数配置

@RequestMapping(value = "/user",method = RequestMethod.POST)
// 返回值中存在实体类，就会被扫描到Swagger中
public User user(@RequestBody User user){
    String username = user.getUsername();
    String password = user.getPassword();
    System.out.println("username = " + username);
    System.out.println("password = " + password);
    return new User(username,password);
}

总结

1. 我们可以通过Swagger给一些比较难理解的属性或者接口， 增加注释信息

2. 接口文档实时更新

3. 可以在线测试