swagger详细教程

心已赠人 2023-10-17 23:26 75阅读 0赞

环境 ; maven项目 , springboot+spring+mybatis ,JDK1.8

**一. 引入swagger jar包**

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

**二. 编写配置类**

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.WebMvcConfigurer;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.ApiKey;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    import static com.google.common.collect.Lists.newArrayList;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig implements WebMvcConfigurer {
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
        }
    
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
    //            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.modules.oss.controller")) //这个路径需要根据你自己的项目层级来写
                .paths(PathSelectors.any())
                .build();
    //            .securitySchemes(security());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                .title("测试项目api")
                .description("测试项目后台api接口文档")
                .termsOfServiceUrl("https://blog.csdn.net")
                .version("2.1")
                .build();
        }
        private List<ApiKey> security() {
            return newArrayList(
                new ApiKey("token", "token", "header")
            );
    	}
    }

**三. 接口类**

@Api(value = "分类",description = "分类接口")
    @RestController
    @RequestMapping("oss/sysclassify")
    public class SysClassifyController {
        @Autowired
        private SysClassifyService sysClassifyService;
    
        /**
         * 列表
         */
    
    //    @RequestMapping("/list")
        @ApiOperation(value = "分类列表",notes = "列表")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "params",value = "map集合",paramType = "query",dataType = "int",required = true)
        })
        @PostMapping("/list")
    //    @RequiresPermissions("oss:sysclassify:list")
        public R list(@RequestParam Map<String, Object> params){
            PageUtils page = sysClassifyService.queryPage(params);
    
            return R.ok().put("page", page);
        }
    
    
        /**
         * 信息
         */
        @ApiOperation(notes = "测试查询单个分类接口",value = "查询分类")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id",value = "分类ID",paramType = "path",dataType = "Long",required = true)
        })
        @GetMapping("/info/{id}")
        public R info( @PathVariable("id") Long id){
    			SysClassifyEntity sysClassify = sysClassifyService.selectById(id);
    
            return R.ok().put("sysClassify", sysClassify);
        }

**四.实体类**

@ApiModel
    @TableName("sys_classify")
    public class SysClassifyEntity implements Serializable {
    private static final long serialVersionUID = 1L;
    
    /**
     * 
     */
    @ApiModelProperty("分类ID")
    @TableId
    private Long id;
    /**
     * 类名
     */
    @ApiModelProperty("类名")
    private String name;
    /**
     * 上级id
     */
    @ApiModelProperty("上级id")
    private Long parentid;
    /**
     * 所属层级
     */
    @ApiModelProperty("所属层级")
    private Integer level;
    /**
     * 分类类型：1 区域分类 2 内部分类
     */
    @ApiModelProperty("分类类型：1 区域分类 2 内部分类")
    private Integer type;
    /**
     * 分类分组：1 区域分类 2 内部分类
     */
    @ApiModelProperty("1 区域分类 2 内部分类")
    private Integer group;

**五 . 访问地址**  
刚开始我也是按照上面的配置弄好以后,一直不显示我配置的那几个接口,后来才知道,访问的地址不对 , 正确的地址是  
http://localhost:8080/swagger-ui.html  
当然上边是根路径是 "/"的时候 ,  
如果你的根路径是带有项目名的,那就是这样  
http://localhost:8080/你的项目名/swagger-ui.html  
注意 : 地址千万不要搞错,要不然你会怀疑自己的配置是否出问题 然而呢,有时候并不是配置出问题,而是你没有去正确的地址查看

**六.国际化(接口测试页面显示中文)**  
![这里写图片描述][70]  
根据上面jar包的层级,在你的项目下创建同样的目录结构  
![这里写图片描述][70 1]  
你自己新建的swagger-ui.html里的内容复制下边的代码粘贴进去即可

<!DOCTYPE html>
    <html>
    <head>
        <meta charset="UTF-8">
        <title>Swagger API</title>
        <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
        <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
        <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
        <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
        <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
        <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
        <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>
    
        <link href='/spring-boot-mybatis/src/main/resourse/META-INF/resources/swagger.css' type='text/css'/>
    
        <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>
    
        
        <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
        <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
        <style type="text/css">
    
    
    
        </style>
    </head>
    
    <body class="swagger-section">
    <div id='header'>
        <div class="swagger-ui-wrap">
            <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" /><span class="logo__title">swagger</span></a>
            <form id='api_selector'>
                <div class='input'>
                    <select id="select_baseUrl" name="select_baseUrl"/>
                </div>
                <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
                <div id='auth_container'></div>
                <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
            </form>
        </div>
    </div>
    
    <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
    <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
    </body>
    </html>

**七.至此大功告成**

END  !!!

[70]: https://img-blog.csdn.net/20180815113226427?watermark/2/text/aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NqYXZhX21hdGg=/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70
[70 1]: https://img-blog.csdn.net/20180815113348610?watermark/2/text/aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NqYXZhX21hdGg=/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70