Knife4j Api文档的增强解决方案

Knife4j Api文档的增强解决方案

 

介绍

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍.

项目模块

模块名称	说明
knife4j	为Java MVC框架集成Swagger的增强解决方案
knife4j-admin	云端Swagger接口文档注册管理中心,集成gateway网关对任意微服务文档进行组合集成
knife4j-extension	chrome浏览器的增强swagger接口文档ui,快速渲染swagger资源
knife4j-service	为swagger服务的一系列接口服务程序
knife4j-front	knife4j-spring-ui的纯前端静态版本,用于集成非Java语言使用
swagger-bootstrap-ui	knife4j的前身,最后发布版本是1.9.6

 业务场景

不使用增强功能,纯粹换一个swagger的前端皮肤，这种情况是最简单的,你项目结构下无需变更

老版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

新版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

 项目Demo示例

Demo示例见另外项目地址： https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

模块	说明
knife4j-spring-boot-demo	在Spring Boot架构下集成knife4j的项目示例
knife4j-spring-boot-single-demo	在Spring Boot单体架构下集成knife4j的项目示例
knife4j-spring-cloud-gateway	在Spring Cloud微服务架构下通过gateway网集成knife4j的示例
swagger-bootstrap-ui-demo-mvc	在Spring MVC模式下集成swagger-bootstrap-ui
swagger-bootstrap-ui-demo	在Spring Boot单体架构下集成swagger-bootstrap-ui
swagger-bootstrap-ui-gateway	在Spring Cloud微服务架构下通过gateway网关集成swagger-bootstrap-ui
swagger-bootstrap-ui-zuul	在Spring Cloud微服务架构下通过zuul网关集成swagger-bootstrap-ui

第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
</dependency>

第二步：创建Swagger配置依赖，代码如下：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

IndexController.java包含一个简单的RESTful接口,代码示例如下：

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}

此时，启动Spring Boot工程，在浏览器中访问： http://localhost:17790/doc.html

https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot-demo

复杂knife4j演示

@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

   /*@Bean
    public UiConfiguration uiConfiguration(){
        return UiConfigurationBuilder.builder()
                .supportedSubmitMethods(new String[]{"GET"})
                .build();
    }*/


   private final TypeResolver typeResolver;
   private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfiguration(TypeResolver typeResolver, OpenApiExtensionResolver openApiExtensionResolver) {
        this.typeResolver = typeResolver;
        this.openApiExtensionResolver = openApiExtensionResolver;
    }


    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        //schema
        List<GrantType> grantTypes=new ArrayList<>();
        //简单模式implicit
        ImplicitGrant implicitGrant=new ImplicitGrant(new LoginEndpoint("http://localhost:8999/oauth/authorize"),"access_token");
        //grantTypes.add(implicitGrant);
        //授权码模式AuthorizationCodeGrant
        TokenRequestEndpoint tokenRequestEndpoint=new TokenRequestEndpoint("http://localhost:8999/oauth/authorize","app1","123");
        //TokenEndpoint tokenEndpoint=new TokenEndpoint("http://192.168.1.10:8080/oauth/token","access_token");
        TokenEndpoint tokenEndpoint=new TokenEndpoint("http://localhost:8999/oauth/token","access_token");
        AuthorizationCodeGrant authorizationCodeGrant=new AuthorizationCodeGrant(tokenRequestEndpoint,tokenEndpoint);
        //grantTypes.add(authorizationCodeGrant);
        //密码模式
        String passwordTokenUrl="http://localhost:8999/oauth/token";
        //String passwordTokenUrl="http://192.168.1.10:8080/oauth/token";
        ResourceOwnerPasswordCredentialsGrant resourceOwnerPasswordCredentialsGrant=new ResourceOwnerPasswordCredentialsGrant(passwordTokenUrl);
        //grantTypes.add(resourceOwnerPasswordCredentialsGrant);
        //客户端模式（client credentials）
        String clientTokenUrl="http://localhost:8999/oauth/token";
        //String clientTokenUrl="http://192.168.1.10:8080/oauth/token";
        ClientCredentialsGrant clientCredentialsGrant=new ClientCredentialsGrant(clientTokenUrl);
        grantTypes.add(clientCredentialsGrant);


        OAuth oAuth=new OAuthBuilder().name("oauth2")
                .grantTypes(grantTypes).build();
        //context
        //scope方位
        List<AuthorizationScope> scopes=new ArrayList<>();
        scopes.add(new AuthorizationScope("read","read all resources"));
        SecurityReference securityReference=new SecurityReference("oauth2",scopes.toArray(new AuthorizationScope[]{}));
        SecurityContext securityContext=new SecurityContext(CollectionUtil.newArrayList(securityReference),PathSelectors.ant("/api/**"));
        //schemas
        List<SecurityScheme> securitySchemes=CollectionUtil.newArrayList(oAuth);
        //securyContext
        List<SecurityContext> securityContexts=CollectionUtil.newArrayList(securityContext);
        List<Parameter> parameters=new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("token").modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true).description("请求Token权限").build());
        parameters.add(new ParameterBuilder()
                .name("token1").modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true).description("请求Token权限1").build());
        parameters.add(new ParameterBuilder()
                .name("xname").modelRef(new ModelRef("string"))
                .parameterType("query")
                .required(true).description("测试").build());
        String groupName="2.X版本";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                //.host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .enableUrlTemplating(false)
                .extensions(openApiExtensionResolver.buildExtensions(groupName))
                //.extensions(openApiExtensionResolver.buildSettingExtensions())
                //.globalOperationParameters(parameters)
                //.securityContexts(securityContexts).securitySchemes(securitySchemes);
                .securityContexts(CollectionUtil.newArrayList(securityContext()))
                .securitySchemes(CollectionUtil.newArrayList(apiKey()))
                ;
        return docket;
    }
    private List<ApiKey> securitySchemes() {
        return CollectionUtil.newArrayList(
                new ApiKey("JWT", "Authorization", "header"));
    }

    @Bean(value = "defaultApi")
    public Docket defaultApi() {


        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("3.默认接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.controller"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions("3.默认接口"))
                //.extensions(openApiExtensionResolver.buildSettingExtensions())
                //.securityContexts(CollectionUtil.newArrayList(securityContext()))
                //.securitySchemes(CollectionUtil.newArrayList(apiKey()));
        .securitySchemes(securitySchemes());
        return docket;
    }
    @Bean(value = "groupRestApi")
    public Docket groupRestApi() {
        List<ResolvedType> list=CollectionUtil.newArrayList();

        //SpringAddtionalModel springAddtionalModel= springAddtionalModelService.scan("com.swagger.bootstrap.ui.demo.extend");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(groupApiInfo())
                .groupName("4.分组接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.group"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo groupApiInfo(){
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui很棒~~~！！！")
                .description("<div style='font-size:14px;color:red;'>swagger-bootstrap-ui-demo RESTful APIs</div>")
                .termsOfServiceUrl("http://www.group.com/")
                .contact("group@qq.com")
                .version("1.0")
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //.title("swagger-bootstrap-ui-demo RESTful APIs")
                .description("# swagger-bootstrap-ui-demo RESTful APIs")
                .termsOfServiceUrl("http://www.xx.com/")
                .contact("xx@qq.com")
                .version("1.0")
                .build();
    }

    private ApiKey apiKey() {
        return new ApiKey("BearerToken", "Authorization", "header");
    }
    private ApiKey apiKey1() {
        return new ApiKey("BearerToken1", "Authorization-x", "header");
    }