springboot1.5 利用swagger构建api文档

一、引入jar

pom.xml

           <!-- swagger -->
        <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.6.1</version>
        </dependency>

二、配置

package com.lyon.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import static com.google.common.base.Predicates.or;
import springfox.documentation.builders.ApiInfoBuilder;
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 static springfox.documentation.builders.PathSelectors.regex;


@Configuration
public class Swagger {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lyon.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("描述:简单优雅的restfun风格")
                .termsOfServiceUrl("http://www.lyon.com")
                //.contact(new Contact("kebi", "tt", "111@qq.com"))//作者
                .version("1.0")
                .build();
    }
    
    @SuppressWarnings("unchecked")
       @Bean
       public Docket commonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("common")
                   .genericModelSubstitutes(DeferredResult.class)
//                   .genericModelSubstitutes(ResponseEntity.class)
                   .useDefaultResponseMessages(false)
                   .forCodeGeneration(true)
                   .pathMapping("/")// base，最终调用接口后会和paths拼接在一起
                   .select()
                   .paths(or(regex("/common/.*")))//过滤的接口
                   .build()
                   .apiInfo(commonApiInfo());
    }
    
    private ApiInfo commonApiInfo() {
        return new ApiInfoBuilder()
                .title("common页面API")//大标题
                .description("springboot平台的REST API")//详细描述
                .version("1.0")//版本
                .contact(new Contact("lyon", "", ""))//作者
                .build();
    }

配置了分组

默认

@Bean
public Docket createRestApi()

添加了分组

@Bean
public Docket commonApi()

分组注意过滤接口地址

.paths(or(regex("/common/.*")))   //过滤的接口

三、Controller

/**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    @ResponseBody
    public User getUserById (@PathVariable(value = "id") Integer id){
        System.out.println("id = " + id);
        
        User user = null;
        if(id == 1){
            user = new User(1, "科比");
        } else {
            user = new User(id, "我是科比粉丝");
        }
        return user;
    }

启用swagger

@EnableSwagger2 可以用在启动类上，也可以加在swaggerConfig 类上

@SpringBootApplication
@EnableSwagger2
public class AppleApplication {

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

测试结果

分组common

@Controller
@RequestMapping("common")
public class CommonController {

    @ApiOperation(value="获取部门详细信息", notes="根据url的id来获取部门详细信息")
    //@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "dept/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Dept getDeptById (@PathVariable(value = "id") Integer id){
        System.out.println("id = " + id);
        
        Dept dept = null;
        if(id == 1){
            dept = new Dept(1, "综合部");
        } else {
            dept = new Dept(id, "其他部门");
        }
        return dept;
    }

四、汉化操作

上面之所以显示中文是实现了汉化

1.在resourece目录下创建META-INF esoures目录，然后创建一个名称为"swagger-ui.html" 的HTML文件。

2.html内容

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</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'/>

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

</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io"><span class="logo__title">swagger</span></a>
        <form id='api_selector'>
            <div class='input'>
                <select id="select_baseUrl" name="select_baseUrl"></select>
            </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>

参考了：

汉化：https://www.jianshu.com/p/7e543f0f0bd8

分组：http://blog.csdn.net/stonexmx/article/details/77604571