springboot集成swagger2

1、创建一个springboot项目，添加swagger2依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

2、配置swagger2配置文件

package com.example.demo.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
// 是否开启swagger，测试环境开始，正式环境要关闭
@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true")
public class SwaggerConfig {
   @Bean
   public Docket createApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               // 可扩展性机制，用于将servlet路径映射（如果有）添加到api基本路径
               .pathMapping("/")
               // 为api选择启动生成器
               .select()
               // 要生成api接口包的路径，这里指demo包下的所有api
               .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(new ApiInfoBuilder()
               // 联系方式
               .contact(new Contact("联系我", "https://www.baidu.com", "123456@qq.com"))
               // 版本号
               .version("1.0")
               // 描述
               .description("测试swagger2")
               // 标题
               .title("springboot集成swagger2")
               .build()
               );
   }
}

创建实体类User

package com.example.demo.entity;

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

@ApiModel(description = "user类")
public class User {
    @ApiModelProperty("用户的id")
    private Integer id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户地址")
    private String address;
    @ApiModelProperty("用户年龄")
    private Integer age;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

3、创建UserController类

package com.example.demo.controller;

import com.example.demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
// 描述user类
@Api(description = "user控制类")
public class UserController {

    @RequestMapping("/test")
    // 标记test方法的作用
    @ApiOperation("测试接口")
    /**
     * 描述参数，多个时用@ApiImplicitParams，单个可以用@ApiImplicitParam,这里的required不等于@Params(required=true)，
     * 只是在使用swagger2框架内必填，不使用swagger2则限制不存在
     */
    @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "用户姓名", defaultValue = "磊哥"),
    @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "北京", required = true)})
    public User test(String name, String address) {
        System.out.println("name: " + name);
        System.out.println("address: " + address);
        User user = new User();
        user.setAddress(address);
        user.setName(name);
        return user;
    }

    @GetMapping("/getByName")
    // 标记test方法的作用
    @ApiOperation("根据名字获取用户")
    // 这里的required不等于@Params(required=true)，只是在使用swagger2框架内必填，不使用swagger2则限制不存在
    @ApiImplicitParam(name = "name", value = "用户姓名", defaultValue = "磊哥", required = true)
    public User getByName(String name) {
        System.out.println("name: " + name);
        User user = new User();
        user.setName(name);
        return user;
    }

    @PutMapping("/addUser")
    // 标记test方法的作用
    @ApiOperation("添加用户")
    public User addUser(@RequestBody User user) {
        System.out.println("name: " + user.getName());
        user.setName("张三");
        user.setAddress("深圳");
        return user;
    }
}

4、配置文件application.properties

swagger.enabled=true
server.port=8081

5、启动项目，浏览器访问 localhost:8081/swagger-ui.html，结果如下



6、修改配置文件application.properties

swagger.enabled=false
server.port=8081

7、启动项目，浏览器访问 localhost:8081/swagger-ui.html，结果如下

8、集成swagger-bootstrap-ui
1、替换掉springfox-swagger-ui依赖：

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
</dependency>

2、添加swagger-bootstrap-ui依赖

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

3、启动项目，访问http://localhost:8080/doc.html，效果如下：