10分钟学会Swagger

Posted 2021-05-18 Harris-H

10分钟学会Swagger

0.前置知识

oas：OpenAPI Specification 即(OpenAPI 规范)

官方文档：https://swagger.io/

1.导入依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2.在启动类上添加注解

@EnableOpenApi

@SpringBootApplication
@EnableOpenApi
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

3.关于Docket

它是一个swagger的一个插件类

自定义swagger

// 构造方法,需要传入一个documentationType类
public Docket(DocumentationType documentationType) {
        this.apiInfo = ApiInfo.DEFAULT;
        this.groupName = "default";
        this.enabled = true;
        this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
        this.applyDefaultResponseMessages = true;
        this.host = "";
        this.pathMapping = Optional.empty();
        this.apiSelector = ApiSelector.DEFAULT;
        this.enableUrlTemplating = false;
        this.vendorExtensions = new ArrayList();
        this.globalRequestParameters = new ArrayList();
        this.documentationType = documentationType;
    }

我们可以调用apiInfo() 方法自定信息。

contact 就是简单的一个简单的类(表示作者联系方式的) ，默认为空。

三个属性：name，url，emai

title 页面的标题(string 类型)

这一个板块是apiInfo

ApiInfo 可以通过ApiInfoBuilder 这个类的build()方法来构造

	@Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30).apiInfo(
                new ApiInfoBuilder().contact(new Contact("Herio","www.he-hao.top","[e-mail]"))
                .title("Herio的OpenApi")
                .version("v1.0")
                .description("这是一段介绍")
                .build()
        );
    }

值得注意的是默认的contact的url 你在页面上点击后跳转会自动加上前缀：

http://localhost:8080/swagger-ui/ ，这个应该可以手动修改。

4.接口添加注释

@Api(tags="Hello控制器")
public class HelloController {

    @ApiOperation(value="测试请求",notes="备注的方法")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

5.只扫描某一类或某一个包下的接口

@Bean
//只扫描以/hello 开头的接口
    public Docket docket1(){
        return new Docket(DocumentationType.OAS_30)
        .groupName("group2").select().paths(PathSelectors.ant("/hello/**")).build();
    }

//只扫描com.example.swagger.controller 包下的接口
@Bean
    public Docket docket2(){
        return new Docket(DocumentationType.OAS_30).groupName("group3")
        .select().apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")).build();
    }

6. 使用第三方UI

---

7.学习文章

传送门