SpringBoot 集成Swagger生成在线API文档

前后端分离，后台负责写接口。随着接口越来越多，接口清单越来越重要，传统是需要自己去维护一个doc的文档或者公司统一放在一个接口清单的web服务上。每次开发者需要单独添加上去。修改后还需要维护。现接入swagger，通过简单的注解即可生成文档，并且随着接口变化自动会变化。统一管理方便快捷

引入jar包
配置swagger相关设置
swagger相关注解

1.通过pom文件引入相应的jar包

　　

 <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、在代码中配置Swagger相关配置（SwaggerConfig）

package org.xftm.app.config;

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;

/**
 * @author : Aaron
 *
 * create at:  2019-12-20  16:20
 *
 * description: api接口配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("API接口文档") //页面标题
        .description("接口管理")//详细描述
        .version("1.0.0") //版本号
        .build();
  }
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("org.*")) //这里写的是API接口所在的包位置

        .paths(PathSelectors.any())
        .build();
  }
}

3、常见Swagger注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
其它若干
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit

 

 

4、实际使用（controller类）

@Api(tags = "APP接口")
@RestController
@RequestMapping("/AppCtrl")
public class AppCtrl

 

5、方法上使用

 //        @PreAuthorize("hasRole('admin')")
    @RequestMapping("/loginByUserNameAndPwd")
    @ApiOperation(value = "用户名密码登陆",produces = MediaType.APPLICATION_JSON_VALUE)
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query",name="username",dataType="String",required=true,value="用户名"),
        @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户密码",defaultValue = ""),
        @ApiImplicitParam(paramType="header",name="token",dataType="String",required=false,value="演示token",defaultValue = "")
    })
    public ResultInfo<org.xftm.sys.vo.UserVo> loginByUserNameAndPwd(String username, String password) throws Exception{

        log.error("传入的用户名：{},用户密码:{}",username,password);


        return userService.loginByUserNameAndPwd(username,password);
    }

 6、访问http://localhost:8080/view/swagger-ui.html  view为项目名

 

 

 

 

7、生成漂亮的ui界面

　pom加入

 <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>

 

访问地址http://localhost:8080/view/docs.html view为项目名

 

界面如下：

 

 

 

 

　　

 

最后、访问地址 http://localhost:8080/view/swagger-ui.html  view为项目名