swagger与springboot的集成

swagger与Springboot的集成

引入依赖

在maven环境中:

在pom.xml中引入如下配置

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在gradle环境中:(我使用的)

在build.gradle中 添加:

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

最简使用

创建config配置类

用来创建swagger相关的配置信息

开启swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

其实这样swagger就能够访问了

编写controller

@RestController
public class MyController {

    @RequestMapping("/h1")
    public String h1(){
        return "hello";
    }

}

直接测试运行

/swagger-ui.html

可以直接访问到当前的这个页面

扩展使用

一般扩展…都是针对于上面的那个页面,有些时候要将以上一些信息隐藏或者修改一些数据

而这些数据保存在哪儿呢?

这里我们需要在config中添加一些东西:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

}

向springcontext中注册一个Docket也就是swagger记事,其实也就主要是对于上面页面的一个记事

查看new Docket()构造函数源码

public Docket(DocumentationType documentationType) {
  this.documentationType = documentationType;
}

既然如此,那么就应该创建一个DocumentType对象

神奇的是,DocumentType类中三个有静态属性,能返回构造的DocumentType

public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0"); 
public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");

一般用swagger2.0即可

对于Docket.java

public Docket extensions(List<VendorExtension> vendorExtensions) {
    this.vendorExtensions.addAll(vendorExtensions);
    return this;
}

public Docket apiInfo(ApiInfo apiInfo) {
    this.apiInfo = defaultIfAbsent(apiInfo, apiInfo);
    return this;
}

public Docket securitySchemes(List<? extends SecurityScheme> securitySchemes) {
    this.securitySchemes = securitySchemes;
    return this;
}

public Docket securityContexts(List<SecurityContext> securityContexts) {
    this.securityContexts.addAll(securityContexts);
    return this;
}

public Docket groupName(String groupName) {
    this.groupName = defaultIfAbsent(groupName, this.groupName);
    return this;
}

public Docket pathProvider(PathProvider pathProvider) {
    this.pathProvider = pathProvider;
    return this;
}

public Docket globalResponseMessage(RequestMethod requestMethod,
                                    List<ResponseMessage> responseMessages) {

    this.responseMessages.put(requestMethod, responseMessages);
    return this;
}

public Docket globalOperationParameters(List<Parameter> operationParameters) {
    this.globalOperationParameters.addAll(nullToEmptyList(operationParameters));
    return this;
}

public Docket ignoredParameterTypes(Class... classes) {
    this.ignorableParameterTypes.addAll(Arrays.asList(classes));
    return this;
}

public Docket produces(Set<String> produces) {
    this.produces.addAll(produces);
    return this;
}

public Docket consumes(Set<String> consumes) {
    this.consumes.addAll(consumes);
    return this;
}

@Incubating("2.3")
public Docket host(String host) {
    this.host = defaultIfAbsent(host, this.host);
    return this;
}

public Docket protocols(Set<String> protocols) {
    this.protocols.addAll(protocols);
    return this;
}

public Docket alternateTypeRules(AlternateTypeRule... alternateTypeRules) {
    this.ruleBuilders.addAll(from(newArrayList(alternateTypeRules)).transform(identityRuleBuilder()).toList());
    return this;
}

public Docket operationOrdering(Ordering<Operation> operationOrdering) {
    this.operationOrdering = operationOrdering;
    return this;
}

public Docket directModelSubstitute(final Class clazz, final Class with) {
    this.ruleBuilders.add(newSubstitutionFunction(clazz, with));
    return this;
}

public Docket genericModelSubstitutes(Class... genericClasses) {
    for (Class clz : genericClasses) {
        this.ruleBuilders.add(newGenericSubstitutionFunction(clz));
    }
    return this;
}

public Docket useDefaultResponseMessages(boolean apply) {
    this.applyDefaultResponseMessages = apply;
    return this;
}

public Docket apiListingReferenceOrdering(Ordering<ApiListingReference> apiListingReferenceOrdering) {
    this.apiListingReferenceOrdering = apiListingReferenceOrdering;
    return this;
}

public Docket apiDescriptionOrdering(Ordering<ApiDescription> apiDescriptionOrdering) {
    this.apiDescriptionOrdering = apiDescriptionOrdering;
    return this;
}

public Docket enable(boolean externallyConfiguredFlag) {
    this.enabled = externallyConfiguredFlag;
    return this;
}

public Docket forCodeGeneration(boolean forCodeGen) {
    if (forCodeGen) {
        genericsNamingStrategy = new CodeGenGenericTypeNamingStrategy();
    }
    return this;
}

public Docket pathMapping(String path) {
    this.pathMapping = Optional.fromNullable(path);
    return this;
}

@Incubating("2.1.0")
public Docket enableUrlTemplating(boolean enabled) {
    this.enableUrlTemplating = enabled;
    return this;
}

public Docket additionalModels(ResolvedType first, ResolvedType... remaining) {
    additionalModels.add(first);
    additionalModels.addAll(newHashSet(remaining));
    return this;
}

public Docket tags(Tag first, Tag... remaining) {
    tags.add(first);
    tags.addAll(newHashSet(remaining));
    return this;
}

由于以上是返回的this,那么可以进行链式调用,因此在编写swagger配置类的时候可以这样写:

 @Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("这是组名")
        .apiInfo(new ApiInfo("标题", "description描述",
                             "版本0.1",
                             "服务条款网址",
                             "contactName联系人",
                             "license许可","licenseUrl"))
        .useDefaultResponseMessages(true)
        .forCodeGeneration(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller"))
        .paths(PathSelectors.any())
        .build();
}

然后这里面的一些内容,具体的使用可以根据上面的方法源码和下面的属性去修改

…

反正说实话,我觉得apifox比这个好用