栏目分类:
子分类:
返回
名师互学网用户登录
快速导航关闭
当前搜索
当前分类
子分类
实用工具
热门搜索
名师互学网 > IT > 软件开发 > 后端开发 > Java

狂神说swagger笔记

Java 更新时间: 发布时间: IT归档 最新发布 模块sitemap 名妆网 法律咨询 聚返吧 英语巴士网 伯小乐 网商动力

狂神说swagger笔记

1.简介

号称世界上最流行的API框架

RestFul Api文档在线自动生成工具=》api文档与API定义同步更新

直接运行,可以在线测试API接口

支持多种语言

官网:https://swagger.io/

2.项目中使用Swagger

需要的jar包

注意:我这里使用的2.6.5的springboot,只支持3.0.0的swagger

  • swagger2

    
        io.springfox
        springfox-swagger2
        3.0.0
    
    
  • swaggerui

    
        io.springfox
        springfox-swagger-ui
        3.0.0
    
    
  • springfox

    
    
        io.springfox
        springfox-boot-starter
        3.0.0
    
    

这里我们使用springboot集成swagger

  • 新建一个springboot-web项目

  • 导入相关依赖

  • 编写一个helloworld工程

  • 配置swagger 编写一个configure类

    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2 //开启Swagger2
    public class SwaggerConfig {
    }
    
  • 测试运行

2.x版本的swagger访问http://localhost:8080/swagger-ui.html

3.x版本的swagger访问http://localhost:8080/swagger-ui/index.html

3.配置swagger

swagger的bean实例Docket

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.ArrayList;


@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("hty","http://localhost:8080","1156388927@qq.com");
        return new ApiInfo(
                "hty的swagger",
                "hty的swagger",
                "1.0",
                "http://localhost:8080",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}
4.swagger配置扫描接口

有一个方法是Docket中的select方法

package com.hty.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
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.ArrayList;


@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否出在自己设定的环境当中 我们想要在测试环境中使用 不要再发布环境中使用
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable设置swagger是否启动  目前是由外部环境所配置
                .enable(flag)
                .select()
                //RequestHandlerSelectors  配置要扫描接口的方式
                //basePackage 指定要扫描的包
                //any()扫描全部
                //none()不扫描
                //withClassAnnotation 扫描类上的注解  参数是一个注解反射对象
                //withMethodAnnotation 扫描方法上的注解  参数是一个注解反射对象
                .apis(RequestHandlerSelectors.basePackage("com.hty.controller"))
                //paths()  过滤什么路径
                //ant()  过滤的路径
//                .paths(PathSelectors.ant("/hty/**"))
                .build();
    }
    //配置swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("hty","http://localhost:8080","1156388927@qq.com");
        return new ApiInfo(
                "hty的swagger",
                "hty的swagger",
                "1.0",
                "http://localhost:8080",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

5.配置API文档的分组

修改Docket中的groupName属性即可,若要配置多个组,就需要多个Docket

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
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.ArrayList;


@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group4");
    }
}

6.给让实体类也让swagger生成api

解决方案就是:在controller中返回一个实体类对象,之后swagger就会在api中的model中生成一个实体类

//只要接口中返回值中存在实体类,就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
    return new User();
}
7.给实体类加文档注释
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")//给类加一个api注释
public class User {

    @ApiModelProperty("用户名")//给字段加一个api注释
    private String name;
    @ApiModelProperty("密码")//给字段加一个api注释
    private String password;

}

效果

8.给Controller加文档注释
//给一个controller的方法加注释
@ApiOperation("Hello控制类")

9.给参数加文档注释
public String hello(@ApiParam("用户名") String username){
    return "hello";
}

10.swagger对接口进行测试

有一个try it out按钮

然后设置用户名,设置完成点击execute

就可以看见最终的效果了

转载请注明:文章转载自 www.mshxw.com
本文地址:https://www.mshxw.com/it/950603.html
我们一直用心在做
关于我们 文章归档 网站地图 联系我们

版权所有 (c)2021-2022 MSHXW.COM

ICP备案号:晋ICP备2021003244-6号