java服务器使用swagger自动生成API文档

原创 2017年10月12日 14:25:24

1.下载swaggerui,放入工程resource下

GitHub-swagger-ui

注意编辑index.html

      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = window.location.toString();
        url = url.substring(0, url.lastIndexOf("/docs")) + "/test/swagger.json";
      }

2.编辑POM

    <dependencies>
        <!-- swagger -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-jersey2-jaxrs</artifactId>
            <version>1.5.3</version>
        </dependency>
    </dependencies>
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
                <includes>
                    <include>*.properties</include>
                    <include>*.xml</include>
                </includes>
            </resource>
            <resource>
                <directory>src/main/resources/swaggerui</directory>
                <filtering>true</filtering>
                <includes>
                    <include>**/*</include>
                </includes>
                <targetPath>swaggerui/</targetPath>
            </resource>
        </resources>
    </build>


3.编辑Main.java,添加两个函数。

    import io.swagger.jaxrs.config.BeanConfig;

    public static Server startServer() throws Exception {
        ...

        //swagger
        buildSwagger();
        handlerList.addHandler(buildSwaggerUI());

        ...
    }

    private static void buildSwagger() {
        // This configures Swagger
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setResourcePackage("com.test.mavenproject.rest");
        beanConfig.setScan(true);
        beanConfig.setBasePath("/test");
        beanConfig.setDescription("Entity Browser API to demonstrate Swagger with Jersey2 in an "
                + "embedded Jetty instance, with no web.xml or Spring MVC.");
        beanConfig.setTitle("Entity Browser");
    }

    private static ContextHandler buildSwaggerUI() throws Exception {
        final ResourceHandler swaggerUIResourceHandler = new ResourceHandler();
        swaggerUIResourceHandler.setResourceBase(Main.class.getClassLoader().getResource("swaggerui").toURI().toString());
        final ContextHandler swaggerUIContext = new ContextHandler();
        swaggerUIContext.setContextPath("/docs");
        swaggerUIContext.setHandler(swaggerUIResourceHandler);
        return swaggerUIContext;
    }

4.编辑TestJerseyConfig.java

import io.swagger.jaxrs.listing.ApiListingResource;

//packages("com.test.mavenproject.rest");

改为

packages("com.test.mavenproject.rest", ApiListingResource.class.getPackage().getName());

5.编辑服务类

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;


@Api("Session")
@Path("test1")
public class TestResource {
    @Inject
    public TestResource(
    ) {
        
    }
    
    @ApiOperation(
            value = "Get测试"
    )
    @GET
    @Path("get")
    @Produces(MediaType.TEXT_PLAIN)
    public String getTest(){
        return "called Get";
    }
}
更详细的Api介绍All Classes(swagger-annotation)


完成后访问 http://服务器地址:端口/docs

使用apidocJs快速生成在线文档

apidoc是一个轻量级的在线REST接口文档生成系统,支持多种主流语言,包括Java、C、C#、PHP和Javascript等。使用者仅需要按照要求书写相关注释,就可以生成可读性好、界面美观的在线接...
  • xialei199023
  • xialei199023
  • 2017年03月18日 10:40
  • 6789

一个给 Java 程序员用的 Api 文档生成工具

api 文档作为前后端同学的沟通桥梁,其重要性是不言而喻的。目前通用的工具有像apidoc/apidoc,caixw/apidoc 这样的第三方库,虽然具有语言无关的特性,但是真正用起来额外多了很多工...
  • koukou234
  • koukou234
  • 2017年08月15日 09:23
  • 1678

利用eclipse生成API文档

制作目的: 提供了很多官方的介绍和类、方法、变量的解释。由于我主要是做Android开发,还提供自己封装的一些公用方法和组件。如果开发人员对正在使用的类不熟悉,想查看类里面的变量或者方法,就可以打开J...
  • MrZhang_happy
  • MrZhang_happy
  • 2016年06月02日 17:47
  • 2578

java类生成API文档

利用eclipse生成API文档
  • hello_word2
  • hello_word2
  • 2017年02月16日 17:51
  • 2470

codeigniter集成Swagger自动化生成RESTFUL文档

最近用CI写一个移动APP的服务器端RESTFUL接口。在开发过程中与前端开发人员沟通接口至关重要。原来我们一直使用WORD文档,上传到QQ群供前端开发下载。虽然工作进行没什么大问题,但是每次写完代码...
  • webchengxuyuan
  • webchengxuyuan
  • 2015年09月11日 14:05
  • 1921

springmvc集成swagger实现接口文档自动化生成

一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮           Swagger 是一个规范和完整的框架,用于生成、描述...
  • liufei198613
  • liufei198613
  • 2016年07月01日 16:17
  • 7473

使用swagger作为restful api的doc文档生成

初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了...
  • q1512451239
  • q1512451239
  • 2016年12月07日 10:32
  • 2717

swagger和springmvc结合自动生成api接口文档

swagger和springmvc结合自动生成api接口文档
  • u011276324
  • u011276324
  • 2016年11月01日 17:35
  • 6111

Java Restfull API 文档生成 Swagger UI

原文地址:http://javatech.wang/index.PHP/archives/74/ 笔者目前正在搭建一套API服务框架,考虑到客户端能够更方便的调用API服务(这里说的更方便是指避...
  • zhangqipu000
  • zhangqipu000
  • 2017年03月06日 18:15
  • 5341

使用JavaDoc风格注释让doxygen自动生成文档

为代码写注释一直是大多开发人员有些困扰的事情。当前开发人员都能接受为了程序的可维护性、可读性编码的同时写注释的说法,但对哪些地方应该写注释,注释如何写,写多少等这些问题,很多开发人员仍然没有答案。更头...
  • liuxuezong
  • liuxuezong
  • 2011年08月24日 09:36
  • 8100
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:java服务器使用swagger自动生成API文档
举报原因:
原因补充:

(最多只允许输入30个字)