swagger的使用

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/Gyb_csdn/article/details/75123575

最近需要使用swagger实现自动生成接口文档的功能。
首先就是疯狂百度呀,结果搞了一天没出来,遇到各种坑。
废话以后再说,先说我做出来的成果。
1、配置
项目采用java注解的方式配置,无xml文件。
首先看我的另一个博客:配置web框架spring+SpringMVC
http://blog.csdn.net/Gyb_csdn/article/details/73771071
接下来都是基于这些配置文件
用到的jar包(gradle配置):
‘com.mangofactory:swagger-springmvc:1.0.2’, //swagger 生成API
‘org.ajar:swagger-spring-mvc-ui:0.4’

2、找到WebConfig这个类,在类上加个@EnableSwagger注解
@ComponentScan里是springmvc扫描的controller层,正好也是文档扫描的层
整个文件如下:

package com;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.ViewResolver;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import org.springframework.web.servlet.view.InternalResourceViewResolver;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration
@EnableWebMvc   //启用Spring MVC组件
@ComponentScan("com.sys.ctrl")  //启用组件扫描
@EnableSwagger  
public class WebConfig extends WebMvcConfigurerAdapter{

    //配置JSP视图解析器
    @Bean
    public ViewResolver viewResolver(){
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();
        resolver.setPrefix("/JSP/");
        resolver.setSuffix(".jsp");
        //可以在JSP页面中通过${}访问beans
        resolver.setExposeContextBeansAsAttributes(true);
        return resolver;
    }

    //配置静态资源的处理
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();//把针对静态资源的请求转交给servlert容器的default servlet处理
    }

    //Swagger的配置==========
    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }


    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        // 暂时不用过滤
        /*return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*pet.*");*/
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                  "My Apps API Title",
                  "My Apps API Description",
                  "My Apps API terms of service",
                  "My Apps API Contact Email",
                  "My Apps API Licence Type",
                  "My Apps API License URL"
            );
        return apiInfo;
    }

    class GtPaths extends SwaggerPathProvider{  
        @Override  
        protected String applicationPath() {  
            return "/restapi";  
        }  
        @Override  
        protected String getDocumentationPath() {  
            return "/restapi";  
        }  
    }  
}

配置就这些了
你在网上肯定也找到了很多,有的单独写个配置类,比如他写的
http://blog.csdn.net/linlzk/article/details/50728264
但是我按照他写的配置以后SpringSwaggerConfig还是无法注入呀!
坑爹,这个一直没解决。。。。。接着说我的
3、controller层
我上面配置扫描的是com.sys.ctrl这个包,所以,在这个包下写Controller层的东西
GroupController类

package com.sys.ctrl;

import java.util.LinkedList;
import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import com.wordnik.swagger.annotations.ApiResponse;
import com.wordnik.swagger.annotations.ApiResponses;

@RestController
@RequestMapping(value = "/group", produces = {"application/json;charset=UTF-8"})
@Api(value = "/group", description = "群组的相关操作")
public class GroupController {

    @RequestMapping(value = "addGroup", method = RequestMethod.PUT)
    @ApiOperation(notes = "addGroup", httpMethod = "POST", value = "添加一个新的群组")
    @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
    public UamGroup addGroup(@ApiParam(required = true, value = "group data") @RequestBody UamGroup group) {
        return group;
    }

    @GetMapping(value = "getAccessibleGroups")
    @ApiOperation(notes = "getAccessibleGroups", httpMethod = "GET", value = "获取我可以访问的群组的列表")
    public List<UamGroup> getAccessibleGroups() {
        UamGroup group1 = new UamGroup();
        group1.setGroupId("1");
        group1.setName("testGroup1");

        UamGroup group2 = new UamGroup();
        group2.setGroupId("2");
        group2.setName("testGroup2");

        List<UamGroup> groupList = new LinkedList<UamGroup>();
        groupList.add(group1);
        groupList.add(group2);

        return groupList;
    }
}

UamGroup类

package com.sys.ctrl;

import com.wordnik.swagger.annotations.ApiModel;
import com.wordnik.swagger.annotations.ApiModelProperty;

/**
 * 群组
 */
@ApiModel
public class UamGroup {
    /**
     * 编号
     */
    @ApiModelProperty(value = "群组的Id", required = true)
    private String groupId;
    /**
     * 名称
     */
    @ApiModelProperty(value = "群组的名称", required = true)
    private String name;
    /**
     * 群组图标
     */
    @ApiModelProperty(value = "群组的头像", required = false)
    private String icon;

    public String getGroupId() {
        return groupId;
    }

    public void setGroupId(String groupId) {
        this.groupId = groupId;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getIcon() {
        return icon;
    }

    public void setIcon(String icon) {
        this.icon = icon;
    }
}

4、与Swagger-UI的整合
刚刚我们做的只是配置了扫描哪些接口,Swagger会把这些接口生成json格式的文档,那谁看的懂,对吧,所以用这个Swagger-UI把json格式的文档转成好看的页面!
效果如下:

这里写图片描述

怎么配置呢?首先去Swagger-UI官网git下载版本2.10的,别下载3.0以上的,否则就出现坑爹的现象,你的页面始终是No operations defined in spec!
像这样,急死人
这里写图片描述
而且你调试发现json格式的接口文档已经拿到了,就是页面展示不出来
这里写图片描述
出现Failed to load spec. 说明第2步没配置好

1)Swagger-UI的git地址:https://github.com/swagger-api/swagger-ui/tree/v2.2.10
下载这里面的dist文件夹,把文件夹整个拷贝到你项目工程的webapp下
2)找到dist文件夹下的index.html文件,把大概第40行的url改成url = “http://localhost:8080/项目名称/api-docs”;注意这个api-docs是固定的,不要改!
这里写图片描述

5、启动项目
浏览器输入http://localhost:8080//InfoIssue/dist/index.html 就看到效果了,成功!
这里写图片描述

吐槽部分
用2天时间总算是做出来了,中间各种坑啊,什么方法都试过了,
1、他的这个也能用http://blog.csdn.net/u011499992/article/details/53455144 而且还有demo下载,框架配置是xml的方式
2、其他参考:http://blog.csdn.net/u010827436/article/details/44417637,这个也不错
3、像这样配置的,我还是没搞出来http://blog.csdn.net/linlzk/article/details/50728264,总是报错
SpringSwaggerConfig无法注入 ,我在spring容器注入了也不行,会报其他错误,就这个配置卡了我一天时间!西吧

阅读更多
想对作者说点什么?

博主推荐

换一批

没有更多推荐了,返回首页