Swagger配置流程

云边小卖部

发布于 2022-12-02 10:06:00

8800

发布于 2022-12-02 10:06:00

文章被收录于专栏：技术分享1

Swagger介绍

在线接口文档的生成工具，且支持用户在线接口测试，优点：

号称时最流行的 API 框架
接口文档在线生成，避免同步的麻烦
可以支持在线对接口执行测试

SpringBoot中集成Swagger

Swagger的原生UI展示的内容主观上没有那么清楚和漂亮，对此有两款对应的Swagger UI的出现，分别为SwaggerBootstrapUI和 knife4j

SwaggerBootstrapUI

导入swagger依赖（SwaggerBootstrapUI）

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.6</version>
   </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
    </dependency>

java

编写Swagger配置类注解：springBoot的配置类注解，swagger启动注解，开启swaggerBootStrapUI Ui界面，为了方便后面参数的修改，可以在yaml中配置参数传入配置类中。 swaggerConfig.java

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean enableSwagger;
    @Value("${swagger.serviceUrl}")
    private String serviceUrl;
    @Value("${swagger.contact}")
    private String contact;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.version}")
    private String version;
    @Value("${swagger.basePackage}")
    private String basePackage;
    @Value("${swagger.description}")
    private String description;
    @Bean
    public Docket createRestApi() {
    //构建全局参数，有需要的在做了解，暂时只需要下面的配置
        ParameterBuilder tokenpar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenpar.name("AuthToken").description("AuthToken")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build(); //header中的ticket参数非必填，传空也可以
        pars.add(tokenpar.build());    //根据每个方法名也知道当前方法在设置什么参数

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //接口的信息
                .enable(enableSwagger)  //swagger接口网站开启配置
                .select()  //初始化并返回一个API选择构造器
                .apis(RequestHandlerSelectors.basePackage(basePackage))//添加包路径选择条件
                .paths(PathSelectors.any()) // 可选择具体路径的筛选（如："/user/"）
                .build()
                .globalOperationParameters(pars); //全局参数的配置
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)    //UI标题
                .description(description)   //详细描述
                .termsOfServiceUrl(serviceUrl) //服务器启动路径
                .contact(contact)   // 作者 
                .version(version)   //版本
                .build();
    }
}
java

界面如图

knife4j

导入依赖

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <!--在引用时请在maven中央仓库搜索最新版本号-->
   <version>2.0.4</version>
</dependency>
java

配置和SwaggerBootstrapUI一样，配置类的注解将@EnableSwaggerBootstrapUI改为@EnableKnife4j。

常用注解

最后附上swagger2常用注解

@Api()用于类；表示标识这个类是swagger的资源

@ApiOperation()用于方法；表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 示例：

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
     @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
     @GetMapping("/getUserInfo")
     public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
     // userService可忽略，是业务逻辑
      User user = userService.getUserInfo();

      return user;
  }
}
java

实体类：

@Data
@ApiModel(value = "微信实体类")
public class WxAuth {

    @ApiModelProperty(value = "用户SessionId",required = true)
    private String sessionId;


    @ApiModelProperty(value = "昵称",required = true)
    private String nickname;

    @ApiModelProperty(value = "头像",required = true)
    private String photo;
}
java

界面展示：