你也许不知道的Swagger高级用法!

Scroll Down

总所周知,我们使用的swagger是这样的↓ image.png

这样的↓

image.png

这样的↓

image.png


页面布局简直反人类. 但是经过我们不动声色的处理后.变成这样的 ↓

image.png

这样的 ↓

image.png

这样的 ↓

image.png

是不是美滋滋.


进入正题:


package com.dm.td.core.config;

import com.baomidou.mybatisplus.core.metadata.OrderItem;
import com.fasterxml.classmate.TypeResolver;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.Ordered;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.AlternateTypeRule;
import springfox.documentation.schema.AlternateTypeRuleConvention;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

import static springfox.documentation.schema.AlternateTypeRules.newRule;

/**
 * @author wajn
 * @date 2019/11/15  21:15
 */
@Profile({"dev", "test"})
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private List<Parameter> getGlobalOperationParameters() {
        List<Parameter> pars = new ArrayList<>(1);
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        // header query cookie
        parameterBuilder.name("DM_AUTH").description("token")
                .modelRef(new ModelRef("string")).parameterType("header").required(false);
        pars.add(parameterBuilder.build());
        return pars;
    }


    @Value("${spring.application.name:服务名称}")
    private String serverName;

    @Bean
    public Docket createRestApi() {
        System.out.println("createRestApi Docket...");
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(getGlobalOperationParameters())
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dm.td.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api接口文档, 调用此接口必须通过网关")
                .description("description接口详细介绍,支持markdown格式")
                .version("1.0")
                .build();
    }


    @Bean
    public AlternateTypeRuleConvention pageableConvention(final TypeResolver resolver) {
        return new AlternateTypeRuleConvention() {
            @Override
            public int getOrder() {
                return Ordered.LOWEST_PRECEDENCE;
            }

            @Override
            public List<AlternateTypeRule> rules() {
                AlternateTypeRule alternateTypeRule = newRule(
                        resolver.resolve(com.baomidou.mybatisplus.extension.plugins.pagination.Page.class)
                        , resolver.resolve(Page.class));
                return new ArrayList<AlternateTypeRule>() {{
                    this.add(alternateTypeRule);
                }};
            }
        };
    }


/**
* 自定义的分页参数说明
*/
    @ApiModel
    @Data
    static class Page {

        @ApiModelProperty("每页显示多少数据,默认为10")
        private long size = 10;
        /**
         * 当前页
         */
        @ApiModelProperty("第多少页,从1开始计数,默认为1")
        private long current = 1;

        /**
         * 排序字段信息
         */
        private List<OrderItem> orders = new ArrayList<>();
    }


}




        <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>


<!--        处理numberformatException异常-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

<!--        处理numberformatException异常-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>


<!--        带你认识全新的swagger-ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>