Java项目怎么使用Swagger生成API文档

小编 • 2023年2月8日下午6:05 • 科技 • 阅读 1172

Swagger号称世界上最流行的Api框架；RestFul Api 文档在线自动生成工具=> Api文档与Api定义同步更新；直接运行，可以在线测试API接口；支持多种语言：（Java，Php…）。在项目中使用Swagger需要springfox。

一、编写API接口文档

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("接口1")
                .apiInfo(apiInfo())
                //默认为true,若改为false则不能在浏览器中访问
//                .enable(false)
                
                .select()
                //RequestHandlerSelectors , 配置要扫描接口的方式
                //basePackage : 指定要扫描的包   basePackage("com.jin.swagger.controller")
                //any() : 扫描全部
                //none() : 不扫描
                //withClassAnnotation : 扫描类上的注解,参数是一个注解的反射现象
                //withMethodAnnotation : 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.jin.controller"))
                //过滤什么路径
//              .paths(PathSelectors.ant("/jin/**"))
                .build();
    }

    @Bean
    public Docket restApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("接口2")
                .apiInfo(apiInfo2())
                .select()
                //none() : 不扫描
                .apis(RequestHandlerSelectors.none())
                .build();
    }

    //配置swagger显示信息
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("酷小亚", "https://blog.csdn.net/weixin_45737330", "384921322@qq.com");
        return new ApiInfo(
                "SwaggerAPI文档————标题！！",
                "不到园林，怎知春色如许————文档描述！",
                "1.0",
                "http://localhost:8080/swagger-ui.html",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }
    private ApiInfo apiInfo2(){
              return new ApiInfo(
                "接口2",
                "接口2描述！",
                "2.0",
                "http://localhost:8080/swagger-ui.html",
                null,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

延伸阅读

什么是java api

API（Application Programming Interface,应用程序编程接口）是一些预先定义的接口，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

运行Java程序时，虚拟机装载程序的class文件所使用的Java API class文件。所有被装载的class文件(包括从应用程序中和从Java API中提取的)和所有已经装载的动态库(包含本地方法)共同组成了在Java虚拟机上运行的整个程序。在一个平台能够支持Java程序以前，必须在这个特定平台上明确地实现API的功能。为访问主机上的本地资源，Java API调用了本地方法。由于Java API class文件调用了本地方法，Java程序就不需要再调用它们了。通过这种方法，Java API class文件为底层主机提供了具有平台无关性、标准接口的Java程序。对Java程序而言，无论平台内部如何，Java API都会有同样的表现和可预测的行为。正是由于在每个特定的主机平台上明确地实现了Java虚拟机和Java API,因此，Java程序自身就能够成为具有平台无关性的程序。