欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

springBoot+swagger2编写接口文档

程序员文章站 2022-03-31 21:18:24
...

Swagger 简介

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

Swagger 快速集成

  • 添加pom依赖
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- 解决FluentIterable.class找不到问题 -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>26.0-jre</version>
</dependency>
<!-- java8 不需要添加,高版本需要添加 -->
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.0</version>
</dependency>

  • 添加配置文件
@Configuration
public class SwaggerConf {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
        		.enable(true)//是否开启swagger接口开发
                .apiInfo(apiInfo())
                .select()
                // 自行修改为自己的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("公司对接文档")
                .description("restful 风格接口")
                //服务条款网址
                //.termsOfServiceUrl("")
                .version("1.0")
                //.contact(new Contact("hello", "url", "email"))
                .build();
    }

}

  • 启动类中添加 @EnableSwagger2注解,开启swagger;
  • 对接口进行api文档注解,不进行注解也会由相关的api,但是没有接口的详细描述,只有开发人员可以看懂。
    常用注解:
@Api()用于类;表示标识这个类是swagger的资源
@ApiOperation()用于方法;
表示一个http请求的操作
@ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
@ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
@ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

springBoot+swagger2编写接口文档
如果项目有拦截请排除以下swagger路径

		"/swagger-ui.html")
        ("/v2/api-docs")
        ("/swagger-resources/**")
        ("/webjars/**")
        ("/cache/**")
  • 最后启动工程,访问http://localhost:8080/swagger-ui.html可以看到以下API文档:
  • springBoot+swagger2编写接口文档
相关标签: springBoot