SpringBoot整合Swagger自动生成API文档

目录

1.引入Swagger依赖（我这里使用的2.2.2版本，尽量别使用新版本，不稳定）

2.编写Swagger配置

 

3.编写Controller

4.一切准备就绪，现在打开网页试试

5.相关的注解解释

6.在此过程中出现的一些问题：

---

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，相比于传统的postman插件，其优点在于：

1. 前后端可以分离开发
2. API文档非常明确
3. 测试的时候不需要输入url链接
4. SpringBoot与Swagger结合非常简单

1.引入Swagger依赖（我这里使用的2.2.2版本，尽量别使用新版本，不稳定）

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
            <scope>compile</scope>
        </dependency>

2.编写Swagger配置

package top.javazhangwei.webconfig;


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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/***
 * 指定API文档页的标题和描述信息等内容。
 */
@Configuration
@EnableSwagger2
public class MySwagger {
   @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("top.javazhangwei.controller"))//这里是controller所处的包名
                .paths(PathSelectors.any())
                .build();
    }
    //构建api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("spring-boot-web-crud项目")
                //描述
                .description("api查询测试接口")
                .termsOfServiceUrl("API terms of service")
                //版本号s
                .version("1.0")
                .build();
    }
}

说明：

• 在这里特别注意下：apis(RequestHandlerSelectors.basePackage("com.yto.controller"))，这个是你Controller所在的包名
• 配置完后，打开http://127.0.0.1:8080/swagger-ui.html#/看是否能访问不

 

3.编写Controller

package top.javazhangwei.controller;

import top.javazhangwei.entities.Diary;
import top.javazhangwei.mapper.DiaryMapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.catalina.servlet4preview.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;
import java.util.List;

@RestController
@Api(description = "测试api")
public class MyController {
    @Resource
    private DiaryMapper diaryMapper;
    //查询文章和用户信息
    @ApiOperation("测试关联查询文章和用户信息")
    @RequestMapping("/testDiary")
    public List<Diary> getAllDiaryAndUsers(HttpServletRequest request){
        List<Diary> list =diaryMapper.getAllDiary();
        return list;
    }
}

@Controller
@Api(description = "登录api")
public class LoginController {
    @Resource
    private UsersMapper usersMapper;
    @ApiOperation("用户登陆")
    @ApiImplicitParams({@ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String",paramType="query"),
            @ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String",paramType="query")})
    @PostMapping(value = "/user/login")
    public String postLogin( @RequestParam("username") String username, @RequestParam("password") String password, HttpSession session, HttpServletRequest request) {
        Users users =usersMapper.login(username,password);
        if(users!=null){
            session.setAttribute("user",users);
            return "redirect:/main.html";
        }else{
            request.setAttribute("msg","用户名或密码错误");
            return "login";
        }
    }

    //返回登录界面

    @RequestMapping("/login")
    @ApiOperation("返回登录界面")
    public String login(){
        return "login";
    }

}

4.一切准备就绪，现在打开网页试试

如果访问不了页面或者页面的数据没改过来，尝试清除一下浏览器缓存~

5.相关的注解解释

其他注解查看官方文档源码： 
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

6.在此过程中出现的一些问题：

       1.出现这种提示：

    很有可能是没在Swagger配置上添加自动配置注解：@EnableSwagger2

    或者就是没有扫到controller，检查检查swagger配置上的包名是否正确

     2.出现failed to parse JSON/YAML response的问题

       这个原因就是拦截器把swagger请求拦截了，所以没有接口信息，只需要加个判断允许swagger允许访问即可。

String url=httpServletRequest.getRequestURI();
 
if(url.indexOf("swagger")!=-1||url.indexOf("api-docs")!=-1){
            return true;
        }