How to document REST API before coding

Question

My team is working on a web application using Micro Service Architecture and Angular + Spring MVC. We follow Agile development. For each story, we create few implementation and test tasks. Documenting REST API is the first task to be done in the story.

We currently document it in Confluence so that developers and testers can work on implementation and test cases respectively.

We are looking to generate REST API documentation with Swagger automatically using codegen. It looks like documenting in Confluence and generating with Swagger is redundant. However, swagger generates accurate documentation.

What is the best way to document REST API before coding ? Are there any other tools ?

Answer 1

Why don't you try the Swagger editor? It allows you to define the API in advance, and you can later replace that documentation with the automatically generated one, if you so desire, without changing its appearance too much.

Anyway, I recognize your problem, it's a bit of a pain to keep the Confluence documentation up to date. Could you possibly set up a continuous integration server to automatically update your Confluence whenever the source code is updated? For Jenkins, there's at least something called the Confluence Publisher Plugin. Confluence also has nice APIs so you could also create some script that the CI server runs and that updates the wiki in some completely custom fashion.

In any case you should have a link to the authoritative source, i.e. the Swagger-generated one, at the top of your Confluence page.

Answer 2

Why not to use Swagger in correlation with coding? The documentation is always in the current version, you don't need to maintain it, you can test it - a lot of benefits in this kind of approach. It is simple to integrate Swagger with Spring MVC. Start with the API (you don't need to implement anything)- so in Spring MVC it would be controllers layer and use it as a skeleton for your app. Here you have a config for Swagger using Docker - wrapper for swagger api.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage(
                        "com.example.controllers"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "Info ...",
                "Info ...",
                "Version ...",
                "",
                new Contact("John Smith", "",
                        "[email protected]"),
                "Copyright 2017 John Smith",
                "");
        return apiInfo;
    }

}

And two dependencies, assuming you use Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0/version>
</dependency>

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

After building and deploying your app Swagger docs would be available

YOUR_SERVER:PORT/swagger-ui.html#/

And example usage in the controller

@ApiOperation(value = "Register user")
@RequestMapping(value = "/users", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ResponseStatus(HttpStatus.CREATED)
public void registerUser(@RequestBody @Valid NewUserRequest newUserRequest) {
    // you don't need to implement it now
}