swagger使用，与SpringMVC合并

转载人：
Swagger分为Swagger spec(JSON/YML)生成，和Swagger-UI展示两部分。
此文章适用于将Swagger-UI和项目绑定为同一http服务时使用。

原文：

为了方便的管理项目中API接口，在网上找了好多关于API接口管理的资料，感觉目前最流行的莫过于Swagger了，功能强大，UI界面漂亮，并且支持在线测试等等，所以本人仔细研究了下Swagger的使用，下面就如何将Swagger与个人的SpringMVC项目进行整合做详细说明：

最终API管理界面：

详细步骤：

Step1:项目中引入相关jar包：

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

<codeclass="language-xml"hljs="">    <properties>

        <project.build.sourceencoding>UTF-8</project.build.sourceencoding>

        <version.spring>3.2.9.RELEASE</version.spring>

        <version.jackson>2.4.4</version.jackson>

    </properties>

 

    <dependencies>

        ....

        <dependency>

            <groupid>com.mangofactory</groupid>

            swagger-springmvc</artifactid>

            <version>0.9.5</version>

        </dependency>

 

        <dependency>

            <groupid>com.fasterxml.jackson.core</groupid>

            jackson-annotations</artifactid>

            <version>${version.jackson}</version>

        </dependency>

        <dependency>

            <groupid>com.fasterxml.jackson.core</groupid>

            jackson-databind</artifactid>

            <version>${version.jackson}</version>

        </dependency>

        <dependency>

            <groupid>com.fasterxml.jackson.core</groupid>

            jackson-core</artifactid>

            <version>${version.jackson}</version>

        </dependency>

    </dependencies></code>

Step2:添加自定义config文件

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

<codeclass="language-java"hljs="">packagecom.spg.apidoc.common.configer;

 

importorg.springframework.beans.factory.annotation.Autowired;

importorg.springframework.context.annotation.Bean;

importorg.springframework.context.annotation.Configuration;

 

importcom.mangofactory.swagger.configuration.SpringSwaggerConfig;

importcom.mangofactory.swagger.models.dto.ApiInfo;

importcom.mangofactory.swagger.plugin.EnableSwagger;

importcom.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

 

/**

 * 项目名称：apidoc

 *

 * @description:

 * @author Wind-spg

 * @create_time：2015年2月10日 上午10:27:51

 * @version V1.0.0

 *

 */

@Configuration

@EnableSwagger

// Loads the spring beans required by the framework

publicclass MySwaggerConfig

{

 

    privateSpringSwaggerConfig springSwaggerConfig;

 

    /**

     * Required to autowire SpringSwaggerConfig

     */

    @Autowired

    publicvoid 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

    publicSwaggerSpringMvcPlugin customImplementation()

    {

        returnnew SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(

                .*?);

    }

 

    privateApiInfo apiInfo()

    {

        ApiInfo apiInfo = newApiInfo(

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

        returnapiInfo;

    }

}</code>

Step3:将此配置加入到Spring容器中，如下：

?

1

<codeclass="language-xml"hljs=""><beanclass="com.spg.apidoc.common.configer.MySwaggerConfig"></bean></code>

Step4:在代码中添加相关APIAnnotation，如下：

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

<codeclass="language-java"hljs="">   @ResponseBody

    @RequestMapping(

            value = addUser, method = RequestMethod.POST, produces = application/json; charset=utf-8)

    @ApiOperation(value = 添加用户, httpMethod = POST, response = BaseResultVo.class, notes = add user)

    publicString addUser(@ApiParam(required = true, name = postData, value = 用户信息json数据) @RequestParam(

            value = postData) String postData, HttpServletRequest request)

    {

        LOGGER.debug(String.format(at function, %s, postData));

        if(null== postData || postData.isEmpty())

        {

            returnsuper.buildFailedResultInfo(-1, post data is empty!);

        }

 

        UserInfo user = JSON.parseObject(postData, UserInfo.class);

        intresult = userService.addUser(user);

        returnbuildSuccessResultInfo(result);

    }</code>

说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

Step5：添加Swagger UI配置

在GitHub上下载SwaggerUI项目，将dist下所有内容拷贝到本地项目webapp下面，结果目录如下图所示：

Step6：修改index.html

将index.html中https://petstore.swagger.wordnik.com/v2/swagger.json修改为https://localhost:8080/{projectname}/api-docs

到此为止，所有配置完成，启动你的项目，访问https://localhost:8080/{projectName}/index.html即可看到如下所示页面：

原贴地址：https://www.2cto.com/kf/201502/376959.html