Swagger

SpringBoot项目

---

---

1.添加Maven

        <!-- swagger  start -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!-- 默认的UI-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!-- swagger  end-->

---

---

2.创建swagger的配置文件
我们可以创建一个文件夹config，专门放置各种配置文件.java
@Configuration是用来让springboot来加载该配置的,然后@EnableSwagger2这个是使用swageer注解。

package com.sun.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .paths(PathSelectors.regex("/.*"))
                .build();
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("我的接口文档",
                "文档描述。。。",
                "1.0.0",
                "API TERMS URL",
                "联系人邮箱",
                "license",
                "license url");
        return apiInfo;
    }
}

运行此项目，然后访问 http://localhost:8080/swagger-ui.html (端口根据自己项目而改变)，发现只有文档，没有具体方法的。只是代表文档可以生成了。（ [basic-error-controller]: Basic Error Controller是基础的，不用关心）

---

---

3.现在在Controller添加文档注释

@RestController
@RequestMapping("/user")
@Api("user")
public class UserController {
    @Autowired
    private UserMapper userMapper;

    @ApiOperation(value = "获取所有用户列表", notes = "")
    @RequestMapping(value = "/allUser", method = RequestMethod.GET)
    @ResponseBody
    public List<User> SelectAll() {
        System.out.println(("----- selectAll method test ------"));
        List<User> userList = userMapper.selectList(null);
        return userList;
    }

    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    public User SelectById(@PathVariable Long id) {
        System.out.println(("----- selectAll method test ------"));
        User user = userMapper.selectById(id);
        return user;
    }


    @ApiOperation(value="添加用户", notes="根据信息添加用户")
    @ApiImplicitParams(@ApiImplicitParam(name ="user", value ="用户详细实体user", required =true, dataType ="User"))
    @RequestMapping(value = "/addUser", method = RequestMethod.PUT)
    @ResponseBody
    public String addUser(@RequestBody User user) {
        User u = new User();
        u.setName(user.getName());
        u.setAge(user.getAge());
        userMapper.insert(u);
        return "success";
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    @ResponseBody
    public String deleteUser(@PathVariable Long id){ 
        userMapper.deleteById(id);
        return"success";
    }

}

再次访问，发现界面已经变化

你可以在这里进行类似的接口测试
1.添加用户

2.获取用户

3.删除用户

---

---

你也可以选择是否开启或者关闭swagger-UI
禁用方法1：使用注解@Profile({"dev","test"}) 表示在开发或测试环境开启，而在生产关闭。（推荐使用）

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})// 设置 dev test 环境开启
public class SwaggerConfig {
...
}

禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.
在原swagger-UI配置文件基础上添加第1,2和7行

1.  @Value("${swagger.enable}")
2.  private boolean enableSwagger;

3.  @Bean
4.  public Docket api(){
5.      return new Docket(DocumentationType.SWAGGER_2)
6.            .apiInfo(apiInfo())
7.            .enable(enableSwagger) //<--- Flag to enable or disable possibly loaded using a property file
8.            .pathMapping("/")
9.            .select()
10.           .paths(PathSelectors.regex("/.*"))
11.           .build();
12      }

在application.properties中添加配置信息

#是否开启swagger,false为关闭
swagger.enable: false

现在访问 http://localhost:8080/swagger-ui.html

---

遇到的错误
在swagger-ui.html中某个controller不显示，原因是

public String loginCheck(String account,String password){
}

应该

public String loginCheck(@RequestParam String account, @RequestParam String password){
}

---

---

这里推荐两个界面。都是引入相应的jar包即可，不需要有任何其他改动。
1.swagger-ui-layer

2.swagger-bootstrap-ui

访问路径也不同了，看官网

        <!-- swagger  start-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!--下面三个都是UI，任选一个-->
        <!--<dependency>-->
            <!--<groupId>io.springfox</groupId>-->
            <!--<artifactId>springfox-swagger-ui</artifactId>-->
            <!--<version>2.2.2</version>-->
        <!--</dependency>-->
        <!--<dependency>-->
            <!--<groupId>com.github.caspar-chen</groupId>-->
            <!--<artifactId>swagger-ui-layer</artifactId>-->
            <!--<version>1.0.0</version>-->
        <!--</dependency>-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.7</version>
        </dependency>
        <!-- swagger  end-->

---

---

<--完-->

---

参考文章：
https://www.jianshu.com/p/cdfa2eacf8ce
https://www.jianshu.com/p/96a5b95cbf29

---

喜欢或者对你有用，就轻轻的点个喜欢就行