springboot+swagger生成API说明文档

springboot+swagger生成API说明文档

springboot+swagger生成API说明文档

记录一下

流程

1. swagger介绍；
2. 导入依赖包；
3. 写配置类；
4. 添加控制接口；
5. 访问 swaggerUI界面；

1. swagger介绍

当前后端分离的时候，通常要自己写接口文档，swagger的出现就免去了自己写接口文档，开发人员只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。（文字太难写了，这段有参考https://www.jianshu.com/p/349e130e40d5）

2. 导入依赖包

在springboot项目中找到pom.xml文件，向文件中添加一下依赖项，添加成功以后项目会自动下载添加的包

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

3. 写配置类

添加swagger2的配置类，可以在项目中新增一个SwaggerConfig类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * @Date: 2020/07/07 09:03
 * @Description: 自动生成api文档的swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XXXX.controller"))
                .paths(PathSelectors.any()).build();
        /*basePackage 是扫描的项目相对路径*/
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXXXX")
                .description("xxy")
                .termsOfServiceUrl("")
                .version("1.0").build();
    }
}

4. 添加控制接口

向控制文件中添加swagger注解

import XXXXX
//引入包文件
@Controller
@RequestMapping("/user")
@Api(tags = "普通用户界面的api")   
public class UserController {
    @Autowired
    MenuService menuService;
    
    @Autowired
    UserService userService;

    Logger logger = LoggerFactory.getLogger(IndexController.class);

    @GetMapping("/index")
    @ApiOperation("普通用户首页动态菜单")
    public ModelAndView mainPage(HttpServletRequest request) {
        ModelAndView view = new ModelAndView();
        Subject subject = SecurityUtils.getSubject();
        User user = (User) subject.getPrincipal();
//        User userRole = userService.getUserRole(user.getUserId());
        user = userService.getUserById(user.getUserId());
        BootstrapTree bootstrapTree = menuService.getBootstrapTree("all");
        request.getSession().setAttribute("bootstrapTree", bootstrapTree);
        request.getSession().setAttribute("sessionUserName", user.getUserName());
        System.out.println(user.getUserHeaderImage());
        request.getSession().setAttribute("sessionHeaderPic", "/images/" + user.getUserHeaderImage());

        /*设置客户端天气*/
//        TodayWeather todayWeather = todayWeatherService.todayWeather(request);
//        logger.info(todayWeather.toString());
//        request.getSession().setAttribute("todayWeather", todayWeather);
        view.setViewName("admin/index");
        return view;
    }
}

swagger api常用注解（参考：https://blog.csdn.net/zhanggonglalala/article/details/98070986）

@Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息

5. 访问 swaggerUI界面；

通常swaggerUI界面的访问网址为：http://localhost:8856/swagger-ui.html#/，即可看到接口文件