添加新的API组

现在假设我要在jhipster 中的代码中新建一个名为noauthapigroup的组，要通过swagger 显示。添加一个swagger的配置类，代码如下

package com.mycompany.myapp.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
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.*;

@EnableSwagger2
@Configuration
public class CustomizeSwaggerConfig {



    public static final Contact DEFAULT_CONTACT = new Contact(
        "chen sir", "http://www.chensir.com", "chensir@gmail.com");



    private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES =
        new HashSet<String>(Arrays.asList("application/json",
            "application/xml","text/html"));


    private static final Set<String> DEFAULT_PROTOCOLS =
        new HashSet<String>(Arrays.asList("http",
            "https"));

    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
            .forCodeGeneration(Boolean.TRUE)
            .groupName("noauthapigroup")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.mycompany.myapp.web.rest.controllers"))
            .paths(PathSelectors.any())
            .paths(Predicates.not(PathSelectors.regex("/logout.*")))
            .build()
            .apiInfo(apiInfo())
            .consumes(DEFAULT_PRODUCES_AND_CONSUMES) //设置请求的content-type的地方 这两个可能搞反，挤不太清楚
            .produces(DEFAULT_PRODUCES_AND_CONSUMES) //设置返回的content-type的地方
            .protocols(DEFAULT_PROTOCOLS);   //这里必须设置，swagger-ui 默认使用https 进行访问，一般来说开发环境都是http的如果不设置，所有的API 都别想调通
    }

    private ApiInfo apiInfo() {

        return new ApiInfo(
            "REST API",
            "REST description of API.",
            "API TOS",
            "Terms of service",
            new Contact("chensir", "http://www.linkedin.com/chensir/", "chensir@gmail.com"),
            "License of API", "API license URL", Collections.emptyList());
    }
}

修改 jhipster 自身的swagger 配置。在application.yaml 中间中，对应的源码是JHipsterProperties.java 这个类

hipster:
    async:
        core-pool-size: 2
        max-pool-size: 50
        queue-capacity: 10000
    # By default CORS is disabled. Uncomment to enable.
    #cors:
        #allowed-origins: "*"
        #allowed-methods: "*"
        #allowed-headers: "*"
        #exposed-headers: "Authorization,Link,X-Total-Count"
        #allow-credentials: true
        #max-age: 1800
    mail:
        from: gateway@localhost
    swagger:
        default-include-pattern: /api/.*
        title: gateway API
        description: gateway API documentation
        version: 0.0.1
        terms-of-service-url:
        contact-name:
        contact-url:
        contact-email:
        license:
        license-url:
        protocols: #重点是这里，添加两个protocol 不然没有http 请求的选项
            - http
            - https

添加之后swagger 可以看到有http 选项出来了

image.png

docket 生成的meta 元数据如下,schema 对应的就是 protocols的设置

{
    "swagger": "2.0",
    "info": {
        "description": "REST description of API.",
        "version": "API TOS",
        "title": "REST API",
        "termsOfService": "Terms of service",
        "contact": {
            "name": "chensir",
            "url": "http://www.linkedin.com/chensir/",
            "email": "chensir@gmail.com"
        },
        "license": {
            "name": "License of API",
            "url": "API license URL"
        }
    },
    "host": "localhost:8080",
    "basePath": "/",
    "tags": [{
        "name": "my-controller",
        "description": "My Controller"
    }],
    "schemes": ["http", "https"],
    "consumes": ["application/xml", "text/html", "application/json"],
    "produces": ["application/xml", "text/html", "application/json"],
    "paths": {
        "/noauth/hello": {
            "get": {
                "tags": ["my-controller"],
                "summary": "sayHello",
                "operationId": "sayHelloUsingGET",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                },
                "deprecated": false
            }
        }
    }
}

jhipster 中分组是通过group 参数来实现的。浏览器中输入下面的连接，可以看到新组的meta 数据
http://localhost:8080/v2/api-docs?group=noauthapigroup

启动swagger

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install -g http-server
http-server

然后访问
http://127.0.0.1:8081/dist 就可以看到swager的界面了

有个重要接口 SwaggerCustomizer 用来做jhipster swagger 的客户化，需要在实现类上标注@component

package com.mycompany.myapp.config;

import io.github.jhipster.config.apidoc.customizer.SwaggerCustomizer;
import io.swagger.models.auth.In;
import org.springframework.core.Ordered;
import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Component;
import springfox.documentation.service.ApiKey;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;


//refernce to swaggerautoconfiguration JHipsterSwaggerCustomizer example

@Component
public class JwtSwaggerCustomzier implements SwaggerCustomizer, Ordered {

    @Override
    public void customize(Docket docket) {
//        add seucurity sechemae
        docket.securitySchemes(Arrays.asList(new ApiKey("Token Access", HttpHeaders.AUTHORIZATION, In.HEADER.name())));
    }

    @Override
    public int getOrder() {
        return 0;
    }
}

SwaggerAutoConfiguration 是 jhipster 的核心配置类