1 swagger简单案例

1.1 加入依赖

<!--swagger图形化接口-->
    <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>

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

1.2 在config包中写swagger配置类SwaggerConfig

swagger配置类的代码如下：（直接套用，但部分需要修改）

package com.ieslab.demo.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 java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        // 设置要现实的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        // 获取项目的环境,如果项目环境在profiles中则返回true
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息
                .groupName("zhangsan")
                .enable(flag)  //配置是否启动swagger
                .select()
                //RequestHandlerSelector配置要扫描接口的方式
                //basePackage：指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))
                /*
                * paths()：只扫描哪些类
                * any()代表扫描全部
                * none()代表都不扫描
                * withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口
                * withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口
                * ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口
                */
                .paths(PathSelectors.any())
                .build();  //工厂模式
    }

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
    }

    //配置 Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("zhangsan","无","[email protected]");

        return new ApiInfo("Swagger API 文档",                    //文档标题
                "这个是一个 Swagger 接口文档。",              //文档描述
                "v1.0",                                       //文档版本
                "没有网站",                   //队伍的网站地址
                contact,                                              //作者信息
                "Apache 2.0",                                  //许可证
                "http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
                new ArrayList());
    }



}

剖析：

在类上要加入两个注解：@Configuration和@EnableSwagger2；

然后开始写docket方法，返回Docket对象，入参是Environment environment，用来后续对application的环境进行判断，控制swagger是否启动：

// 设置要现实的swagger环境,dev代表application-dev.yaml
Profiles profiles = Profiles.of("dev","test");
// 获取项目的环境,如果项目环境在profiles中则返回true
boolean flag = environment.acceptsProfiles(profiles);

接着，返回配置的Docket对象：

return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())  // 配置 Swagger ApiInfo 基本信息,因此要创建apiInfo方法
           .groupName("zhangsan")   
           .enable(flag)  //配置是否启动swagger
           .select()
           //RequestHandlerSelector配置要扫描接口的方式
           //basePackage：指定要扫描的包
           .apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))
           /*
            * paths()：只扫描哪些类,()里的参数有any()、none()、ant(“需要扫描的请求”)、withClassAnnotation、withMethodAnnotation,后面两个不常用，请自行百度
            * any()代表扫描全部
            * none()代表都不扫描
            * withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口
            * withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口
            * ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口
            */
            .paths(PathSelectors.any())
            .build();  //工厂模式
    }

其中，apiInfo传入apiInfo方法返回的ApiInfo对象（需要自己写apiInfo方法），enable传入的参数可由项目的环境决定，apis(RequestHandlerSelectors.basePackage())传入的是需要扫描的包路径，paths()传入的是在包路径下扫描哪些类，groupName() 传入的是测试接口归属哪个人，如下图所示：

多个docket方法就可以代表不同人的测试接口：（注意方法名不要相同！）

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
    }

效果：

apiInfo()方法如下：套模板即可。

    //配置 Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("zhangsan","无","[email protected]");

        return new ApiInfo("Swagger API 文档",                    //文档标题
                "这个是一个 Swagger 接口文档。",              //文档描述
                "v1.0",                                       //文档版本
                "没有网站",                   //队伍的网站地址
                contact,                                              //作者信息
                "Apache 2.0",                                  //许可证
                "http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
                new ArrayList());
    }

1.3 创建实体类User

package com.ieslab.demo.emtity;

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

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("这是User的实体类") // 给实体类加文档注释
public class User {
    @ApiModelProperty("主键id")
    private Integer userId;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

}

剖析：只要实体类在Controller被使用，而控制类又被swagger扫描到，就会被展示出来，实体类的注解都是给文档加注释用的。

1.4 创建UserDao接口和UserDaoImpl实现类

UserDao：

package com.ieslab.demo.dao;

import com.ieslab.demo.emtity.User;

public interface UserDao {
    // 添加用户
    User addUser(Integer userId,String userName,String password);

}

UserDaoImpl：因为前端传来的是一个JSON对象，会使用@RequestBody将其封装为User对象，然后从这个User对象中拿各个属性。

package com.ieslab.demo.dao.impl;

import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import org.springframework.stereotype.Repository;

import java.util.HashMap;
import java.util.Map;

@Repository
public class UserDaoImpl implements UserDao {
    private static Map<Integer,User> userMap = null;
    static {
        userMap = new HashMap<Integer, User>();
        userMap.put(100,new User(100,"zhangsan","777"));
        userMap.put(102,new User(102,"lisi","888"));
        userMap.put(103,new User(103,"wangwu","999"));
        userMap.put(104,new User(104,"zhaoliu","000"));
    }

    @Override
    public User addUser(Integer userId,String userName,String password) {
        User user = new User(userId,userName,password);
        userMap.put(user.getUserId(),user);
        return user;
    }
    
    
}

1.5 创建Controller对象，接收请求

package com.ieslab.demo.controller;
import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Slf4j
@RestController
public class MyController {
    @Autowired // 相当于使用new UserDaoimpl()
    private UserDao userDao;
    @PostMapping(value = "/addUser")
    @ApiOperation(value = "AddUser接口",httpMethod = "POST",notes = "这是AddUser接口的详细说明") // 给方法加注释
    public User addUser(@RequestBody @ApiParam("用户") User userInput){  // 加入@RequestBody Spring自动将传过来的JSON类型的数据和我们的类匹配，说明输入是JSON格式的数据
        User user = userDao.addUser(userInput.getUserId(), userInput.getUsername(), userInput.getPassword());
        return user;
    }

}

剖析：

重点在于Post方法不能接收基本类型的数据，需要把它们用JSON格式进行封装，然后@RequestBody会把JSON格式的数据转为对应的实体类。

注意！类上的是@RestController而不是@Controller，因为@Controller后类中的方法return的要转发的页面，而不会被以指定的格式写入Http response body中。

其他大部分注解都是加注释用的：