Springboot配制Swagger自动生成API文档

一、引入Swagger

1. 添加maven依赖

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

2. 启动swagger

  添加一个最简单的配制类，即可访问swagger首页

SwaggerConfig.java
package com.sc.springboot.config;

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {
    
}

  只要在配制类中开启了swagger，就可以通过http://localhost:8080/swagger-ui.html访问swagger页面

3. 访问出现404问题解决

  如果项目中出现了WebMvcConfigurationSupport配制类，那么application.yml文件中的配制的默认资源访问路径就会失效，所以要重写在新的配制类中，重写资源路径。
  重写addResourceHandlers和configureDefaultServletHandling方法，按下列HeadConfig.java配制即可

HeadConfig.java

package com.sc.springboot.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * Controller跨域处理
 */
@Configuration
public class HeadConfig extends WebMvcConfigurationSupport {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowCredentials(true) //允许携带cookie
                .maxAge(3600); //cookie有效时间,单位：秒
    }

    /*
    * 重新指定资源位置
    * */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }


    /**
     * 配置servlet处理
     */
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}

4. 详细一点的配制

（1）SwaggerConfig.java

package com.sc.springboot.config;

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {

    /*
    * 一个Docket Bean对应一个分组，可添加多个分组
    */
    @Bean
    public Docket docket1(Environment environment){

        /*
        *测试环境可用，这个主要是用来读取当前的运行环境的，
        *只有在开发环境中才启用api文档
        */
        Profiles profiles = Profiles.of("dev","test");

        //通过environment.accptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        
        //添加全局配制，所有的请求都要带上请求头参数
        ParameterBuilder token = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        token.name("token").description("user token")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        pars.add(token.build());
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("默认分组")
                //根据当前的运行环境决定是否启用swagger
                .enable(flag)
                .select()
                //apis可以配置该分组要扫描哪些Controller
                .apis(RequestHandlerSelectors.basePackage("com.sc.springboot.controller"))
                //paths配制过滤路径，可以选择在该组中，显示哪个路径的api
                .paths(PathSelectors.any())
                .build();
                //添加此用户的一些全局配制,这里给所有接口都添加token_id请求头参数
                .globalOperationParameters(pars); 
    }

    //配制Swagger信息=apiInfo()，这是一些界面信息
    private ApiInfo apiInfo(){
        Contact DEFAULT_CONTACT = new Contact("", "", "");
        return new ApiInfo("Demo平台后端接口",
                "Demo平台API",
                "v1.0",
                "",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

  具体可以更改哪些信息，可以直接查看swagger的配制源码

（2）切换生产环境的方式

  在application-dev.yml和application-pro.yml中放主要信息
application.yml中指定开发环境

spring:
  profiles:
    active: dev  # 指定开发环境

二、配制接口信息

1. Controller里的配制

  这里主要是给每一个接口添加请求参数和返回参数

@Api(tags = "登录管理") //对这个controller进行注释
@Controller
@ResponseBody
public class LoginController {

    @ApiOperation("用户注销登录")  //对接口进行描述
    @ApiImplicitParams({  //添加请求参数，可添加多个，paramType是请求的参数位置
            @ApiImplicitParam(name = "token", value = "token信息",paramType = "header")
    })
    @ApiResponses({  //添加返回信息，可返回多个，对应不同的状态吗
            @ApiResponse(code = 200, message = "注销成功"),
            @ApiResponse(code = 401, message = "请登录后操作")
    })
    @GetMapping("sc/logout")
    public User logout(HttpServletRequest request){
        
    }

    @ApiOperation(value = "用户登录")
    @ApiImplicitParams({
                    @ApiImplicitParam(name = "userName", value = "用户名"),
                    @ApiImplicitParam(name = "password", value = "密码")
    })
    @ApiResponses({
            @ApiResponse(code=200,message = "登录成功"),
            @ApiResponse(code=402,message = "用户名或密码错误"),
    })
    @PostMapping("login")
    public User login(@RequestParam String userName,@RequestParam String password, HttpServletResponse response){
        
    }
}

2. Bean里的配制

  对Controller中的参数进行说明后，有的值由于是对象类型的，为了给对象里的属性添加描述，我们需要在Bean类里添加相应的注解

package com.sc.springboot.bean;

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

//给这个实体类添加注释，用@ApiModel
@ApiModel(value = "用户信息信息")  
public class User{
    //给字段添加描述用@ApiModelProperty
    @ApiModelProperty(value = "用户id", dataType = "String")
    private String user_id;
    @ApiModelProperty(value = "用户名称", dataType = "String")
    private String user_name;
    //省略get、set方法
}

3. 项目中的效果

三、总结

  最近项目比较多，都是采取前后端分离方式的，要编写大量的接口，之前我们团队都是利用word或YApi来写接口文档，每次更改都要重新编辑文档，修改版本号，实在是太麻烦了。今天突发奇想，为啥不自动生成文档接口呢，然后就捣鼓了一下，简单记录一下这个过程。
  这个工具确实挺方便的，还可以在首页直接测试，postman都不需要了，不过也有很多坑，比如返回嵌套类型的json数据，下篇再具体说说。