SpringBoot整合Swagger

生成接口文档的工具有很多种，这里我使用了Swagger。

使用工具：idea、maven、springboot、swagger，相关知识参考：swagger官网https://swagger.io。

springboot项目使用swagger有两种方法，一种直接使用第三方依赖，这是最简单的（我这里没有尝试），可以参考https://github.com/SpringForAll/spring-boot-starter-swagger，我使用的是第二种使用官方依赖，如下：

1.引入依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

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

2.spring的swagger配置，主要是把basePackage设置到需要生成文档的package上。

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo2.business.basic"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                //.termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

3.对http://localhost/swagger-ui.html的资源在webconfig中做一些处理，因为这个页面会访问maven引入的jar中的js\css等资源，否则会报404错误，或者无法正确显示该页面。

package com.example.demo2.config;

import com.example.demo2.sysInit.LoginHandlerInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;

@Configuration
@EnableWebMvc
public class webConfig implements WebMvcConfigurer {

    @Bean
    public LoginHandlerInterceptor getLoginHandlerInterceptor() {
        return new LoginHandlerInterceptor();
    }

   @Override
    public void addInterceptors(InterceptorRegistry registry) {
        LoginHandlerInterceptor loginHandlerInterceptor=new LoginHandlerInterceptor();
        //添加忽略路径
        registry.addInterceptor(loginHandlerInterceptor).addPathPatterns("/**")
                .excludePathPatterns("/login","/submit","/static/**","swagger-ui.html","webjars/**");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //swgger访问引用的jar中的文件，需要对路径进行转换
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        //将所有/static/** 访问都映射到classpath:/static/ 目录下
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
    }

}

4.controller添加swagger注释，测试

package com.example.demo2.business.basic.controller;

import com.example.demo2.business.basic.service.GaodeMapService;
import com.example.demo2.business.basic.service.UserService;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

/**
 *  用户控制器
 */
@RestController
@RequestMapping("web/user")
public class UserController {
    @Autowired
    private UserService userService;

    /*
    * @Desciption: 查询昵称是否重复
    * @param nick 昵称
    * @Return: java.lang.String
    * @Author: ada
    * @Date: 2020/2/18 21:01
    * @Version: 1.0
    */
    @GetMapping("checkNick/{nick}")
    @ResponseBody
    public String checkNick(@PathVariable("nick") String nick){
        if(StringUtils.isEmpty(nick.trim())){
            return "查询的昵称不能为空";
        }
        Boolean isFalg=userService.isExistNick(nick.trim());
        if(isFalg){
            return "201";
        }
        return "200";
    }

    /*
     * @Desciption: 查询登录账号是否重复
     * @param uin 登录账号
     * @Return: java.lang.String
     * @Author: ada
     * @Date: 2020/2/18 21:01
     * @Version: 1.0
     */
    @GetMapping("checkUin/{uin}")
    @ResponseBody
    public String checkUin(@PathVariable("uin") String uloginName){
        if(StringUtils.isEmpty(uloginName.trim())){
            return "查询的登录账号不能为空";
        }
        Boolean isFalg=userService.isExistLoginName(uloginName.trim());
        if(isFalg){
            return "201";
        }
        return "200";
    }

    /*
    * @Desciption: 用户注册
    * @param uNickName  昵称
    * @param uLoginName 登录账号
    * @param pwd    登录密码
    * @param tel 手机号码
    * @Return: java.lang.String 201:昵称或账号不可注册 202：四个参数中间存在空 203 添加失败，程序异常 200 成功
    * @Author: ada
    * @Date: 2020/2/19 23:30
    * @Version: 1.0
    */
    @PostMapping("/")
    @ResponseBody
    public String register(@RequestParam("nick") String uNickName,
                           @RequestParam("uin") String uLoginName,
                           @RequestParam("pwd") String pwd,
                           @RequestParam("tel") String tel){
        if(StringUtils.isEmpty(uNickName) || StringUtils.isEmpty(uLoginName) || StringUtils.isEmpty(pwd) ||
                StringUtils.isEmpty(tel)){
            return "202";
        }
        //查询账号  昵称是否重复
        if(userService.isExistNickOrLoginName(uNickName,uLoginName)){
            return "201";
        }
        boolean falg=userService.addUser(uNickName,uLoginName,pwd,tel);
        if(falg){
            return "200";
        }
        return "203";
    }
}

5.打开http://localhost/swagger-ui.html，这里项目端口为80，所以端口没有显示