zoukankan      html  css  js  c++  java
  • spring boot集成Swagger2

    第一步:jar包的引入

    这里我的springboot 和framework都是1.5.9

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

     

    第二步:swagger的配置启动类

    有人说这个类必须放到启动类同级,无稽之谈,扫描包的配置基础去补补。


    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;

    /**
    * 自动文档注解
    * 访问地址:注意端口后面+上context-path
    * springboot中的swagger:http://localhost:8080/swagger-ui.html
    * druid数据库监控 :http://localhost:8080/druid/index.html
    */
    @Configuration
    public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Bean
    public Docket businessDocket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 为当前包路径
    .apis(RequestHandlerSelectors
    .basePackage("com.sanyi.qibaobusiness.core.controller.busniess"))
    .paths(PathSelectors.any())
    .build();
    }

    // 构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
    return new ApiInfoBuilder() // 页面标题
    .title("三易业务端绘图端 API")
    .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
    .contact("lanhaifeng") // 创建人
    .version("1.0") // 版本号
    .description("访问 http://localhost:8080/swagger-ui.html")//描述
    .build();
    }

    /**
    * 我们在访问http://localhost/swagger-ui.html时,这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.2.2.jar里面。
    * SpringBoot自动配置本身并不会把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上这个映射即可
    * 这个也是发生404的解决方案
    * @param registry
    */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    }

     

    三、在启动类加上@EnableSwagger2注解。


    import org.mybatis.spring.annotation.MapperScan;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.boot.builder.SpringApplicationBuilder;
    import org.springframework.boot.web.servlet.ServletComponentScan;
    import org.springframework.boot.web.support.SpringBootServletInitializer;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;


    @EnableSwagger2
    @SpringBootApplication
    //@EnableConfigurationProperties({YmlConfig.class})//不需要了.因为YmlConfig类上有@Component注解
    @MapperScan("com.sanyi.qibaobusiness.core.mapper") //配置扫描mapper接口的地址
    public class QibaobusinessApplication extends SpringBootServletInitializer {


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

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
    return application.sources(QibaobusinessApplication.class);
    }
    }
     

    四、在controller中添加注解

    这些注解看实际使用情况自行添加。

    @Api:用在类上,说明该类的作用
     
    @ApiOperation:用在方法上,说明方法的作用,标注在具体请求上,value和notes的作用差不多,都是对请求进行说明;tags则是对请求进行分类的,比如你有好几个controller,分别属于不同的功能模块,那这里我们就可以使用tags来区分了。
     
    @ApiImplicitParams:用在方法上包含一组参数说明
     
    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面。
     
    @ApiResponses:用于表示一组响应
     
    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
     
    @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model,用于class上
    @ApiModelProperty: 这里顾名思义,描述一个model的属性,就是标注在被标注了@ApiModel的class的属性上,这里的value是对字段的描述,example是取值例子,注意这里的example很有用,
    对于前后端开发工程师理解文档起到了关键的作用,因为会在api文档页面上显示出这些取值来;这个注解还有一些字段取值,可以自己研究,举例说一个:position,表明字段在model中的顺序。

     

    下面罗列下实际开发中最常用的三种写法,注意请求方法必须写。这三种基本够用了。httpMethod这个参数必须设置。

    //注解在类上,其实只有这个value值有效
    @Api(value="/decorate[装修选型版块Controller]", tags="装修选型版块Controller")
    
    //注解在方法上,注意这个httpMethod必须要写,不然各种请求都会帮你罗列出来
    //paramType = "path"这个参数,如果不是请求方法后面直接带参数可以去掉,例如/getUserId/2,这种请求这个参数就需要配置,否则应该去除
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",httpMethod = "GET")//如果没有请求参数,用这个一个就行
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    
    //多个请求参数,注意这里就没有 paramType = "path"。
    @ApiOperation(value="合作方式", notes="选择合作方式",httpMethod = "POST")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "machinePrcie", value = "购买机械价格", required = true, dataType = "Double"),
                @ApiImplicitParam(name = "daystate", value = "按天计算折扣", required = true, dataType = "Double"),
                @ApiImplicitParam(name = "overserPrice", value = "按天计算价格", required = true, dataType = "Double"),
                @ApiImplicitParam(name = "areastate", value = "按面积计算折扣", required = true, dataType = "Double"),
                @ApiImplicitParam(name = "prcie", value = "按面积计算总价", required = true, dataType = "Double")
        })

     

    四、安全验证放过swagger相关

    实际上线则不能放过,或者相关文档删除,相关接口必须对外保密。

    /*swagger*/
            filterChainDefinitionMap.put("/swagger-ui.html", "anon");
            filterChainDefinitionMap.put("/swagger-resources/**", "anon");
            filterChainDefinitionMap.put("/v2/**", "anon");
            filterChainDefinitionMap.put("/webjars/**", "anon");

     

    五、访问:http://localhost:8080/swagger-ui.html

    当出现:fetching resource list: http://localhost:8080/v2/api-docs 时稍微等待一两分钟,之后文档会自动加载出来

  • 相关阅读:
    x64 平台开发 Mapxtreme 编译错误
    hdu 4305 Lightning
    Ural 1627 Join(生成树计数)
    poj 2104 Kth Number(可持久化线段树)
    ural 1651 Shortest Subchain
    hdu 4351 Digital root
    hdu 3221 Bruteforce Algorithm
    poj 2892 Tunnel Warfare (Splay Tree instead of Segment Tree)
    hdu 4031 Attack(BIT)
    LightOJ 1277 Looking for a Subsequence
  • 原文地址:https://www.cnblogs.com/zeussbook/p/10966504.html
Copyright © 2011-2022 走看看